@trayio/cdk-dsl 1.3.0 → 1.5.0

package/README.md

@@ -5,6 +5,10 @@ The CDK Domain Specific Language (DSL) is the main component of Tray's CDK, it i
 A CDK connector consists of code written only using the DSL, which is declarative, so it only describes the connector, that description is then interpreted by the runtime
 to execute a connector's operations.
 
+## Documentation
+
+The [Tray.io Developer Portal](https://developer.tray.io) has the most up to date documentation including a [quick start guide](https://developer.tray.io/developer-portal/cdk/quickstart/) for building connectors with the CDK
+
 
 ## Project Structure
 
@@ -216,7 +220,7 @@ export const myOperationHandler =
     );
 ```
 
-As an example of more complex behaviour, this handler reads a list of products using another operation and converts the result into a simple list of `{text: string, value: string}` pairs, this is known as a Dynamic Data List (DDL) operation used to help users select values as part of configuring workflows within the tray builder.
+As an example of more complex behaviour, this handler reads a list of products using another operation and converts the result into a simple list of text and value pairs, this is known as a Dynamic Data List (DDL) operation used to help users select values as part of configuring workflows within the tray builder.
 
 
 To do this, the handler needs to invoke the regular `getProducts` operation, this is accomplished by using the `invoke` functions that composite handlers have access to, and passing it a **handler reference** and an input (no need to pass the auth value as it will be passed automatically), the handler reference passed to the `invoke` function is the result of the `OperationHandlerSetup.configureHandler()` function, which is why they are saved into a constant and exported like this:
@@ -230,6 +234,22 @@ export const getProductsHandler =
 
 The `getProductsHandler` constant contains the handler reference, which also has the input and output type information as part of its type, to make sure that when invoked or tested, only valid input and output values can be used.
 
+To invoke the handler it is a simple call to the `invoke` function that takes the handler reference as an argument, and returns another function that takes the input type of that handler and returns a `Promise<OperationHandlerResult<T>>` where `T` is the output type of the handler and `OperationHandlerResult` contains a failure response if the call failed or a success response with a value of type `T` if the call was successful:
+
+```typescript
+const productsResult: OperationHandlerResult<GetProductsOutput> = await invoke(getProductsHandler)({ storeId: input.storeId })
+```
+
+The output type of a DDL operation is defined by the `DDLOperationOutput<T>` type, where `T` is the type of the values and can be a string or a number, that type has one field called `results` which is an array of objects of type `{text: string, value: T}`.
+
+To use it as the output, it is recommended to define a custom type for the operation as usual in `output.ts` that derives from `DDLOperationOutput<T>` specifying whether `T` is of type string or number, like this example `output.ts` file:
+
+```typescript
+import { DDLOperationOutput } from '@trayio/cdk-dsl/connector/operation/OperationHandler';
+
+export type GetProductListDdlOutput = DDLOperationOutput<number> //the values of the elements of the DDL are of type number
+```
+
 
 With that in mind, this is what the DDL handler would look like:
 
@@ -238,12 +258,30 @@ With that in mind, this is what the DDL handler would look like:
 export const getProductsDDLHandler = 
     OperationHandlerSetup.configureHandler<AuthType, GetProductsDDLInput, GetProductsDDLOutput>((handler) =>
         handler.usingComposite(async (auth, input, invoke) => {
-                    const productListResult: OperationHandlerResult<GetProductsOutput> = 
+                    //invoke the products operation
+                    const productsResult: OperationHandlerResult<GetProductsOutput> = 
                         await invoke(getProductsHandler)({ storeId: input.storeId })
-                    return OperationHandlerResult.map(
-                        productListResult, 
-                        productList => productList.map(product => { text: product.title, value: product.id })
-                    )
+
+                    //if the invocation failed, propagate the failure
+                    if (productsResult.isFailure) {
+                        return productsResult
+                    }
+
+                    //productsResult is of type `OperationHandlerSuccess` now, because we handled the failure case above, so we can get the value
+                    const products = productsResult.value
+
+                    //converts a product list into a list of text (label) and values (identifiers) for the DDL
+                    const productsDDL = products.map((product) => {
+                        return {
+                            text: product.title,
+                            value: product.id
+                        }
+                    })
+
+                    //returns the DDL list in an object with a "result" value to match the GetProductsDDLOutput type
+                    return OperationHandlerResult.success({
+                        result: productsDDL
+                    })
                })
     );
 ```
@@ -257,11 +295,24 @@ The result of that invocation is of type `Promise<OperationHandlerResult<GetProd
 The `await` keyword unwraps the promise, and we are left with a `OperationHandlerResult<GetProductsOutput>`, which forces the handler to deal with both the failure case as well as the success case.
 
 There are multiple ways to do this
-- Using `if` or `switch` statements to narrow down the type
+- Using `if` or `switch` statements to narrow down the type as shown in the example
 - Using the `OperationHandlerResult.getSuccessfulValueOrFail()` function which unwraps the value if successful or terminates the function propagating the error if it is not
-- As shown in the example, using the `OperationHandlerResult.map()` function.
+- Using the `OperationHandlerResult.map()` function, which takes an `OperationHandlerResult<T>` as an argument and a function to convert `T` to another type in case it is successful, propagating the failure if it is not (works in the same way it works for the map function in `Array<T>`)
+
+Once the handler has access to the product list value, it just needs to convert each element to a `{text: string, value: number}` pair and return that list in an object with a `result` property as shown above.
+
+Finally, for DDL operations, we need to add an extra `type` property in the `operation.json` file with `ddl` as the value:
+
+```json
+{
+    "name": "get_products_ddl",
+    "title": "Get Products DDL",
+    "description": "Returns a DDL with product ids as values and product titles as labels",
+    "type": "ddl"
+}
+```
 
-Once the handler has access to the product list value, it just needs to convert each element to a `{text: string, value: string}` pair.
+This will categorise this operation as a DDL and will exclude it from the list of visible operations of the connector.
 
 ## Testing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trayio/cdk-dsl",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "A DSL for connector development",
   "exports": {
     "./*": "./dist/*.js"
@@ -14,7 +14,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@trayio/commons": "1.3.0"
+    "@trayio/commons": "1.5.0"
   },
   "typesVersions": {
     "*": {