Merge pull request #192 from godspeedsystems/add/guides

add use cases

docs/microservices-framework/config-and-mappings/config.md

@@ -20,8 +20,6 @@ The configuration files under `config/` directory can have specific naming conve
 
 Environment variables in Godspeed are essential for securely managing configuration details like API keys, database URLs, and other sensitive information. Godspeed allows two primary ways to configure and access these variables.
 
-> **Note**: For sensitive information such as secrets or passwords, it is recommended to use environment variables in this way to avoid hardcoding values directly in your configuration files.
-
 ### Configuration Setup for Environment Variables
 
 Environment variables can be set up using: 

docs/microservices-framework/config-and-mappings/mappings.md

@@ -35,7 +35,44 @@ If the file name is index.yaml then its content is available directly at global
 However, for other file names you need to mention the file name while accessing the mappings object like `mappings.generate.genId`
 :::
 
-Sample workflow accessing mappings object:
+### Sample Datasource Configuration using Mappings
+  ```yaml
+   # /src/datasources/aws.yaml
+   type: aws
+   default_client_config:
+     region: <% mappings.aws_region %>
+   services:
+     s3:
+       type: s3
+       config:
+         bucket: <% mappings.aws_s3_bucket %>
+     dynamodb:
+       type: dynamodb
+       config:
+         tableName: <% mappings.aws_table_name %>
+   ```
+   **Explanation**:
+   - `aws_region`, `aws_s3_bucket`, and `aws_table_name` are defined in `mappings`.
+   - This configuration dynamically injects these values into the datasource.
+
+---
+
+### Sample Event Source Configuration using Mappings
+  ```yaml
+   # /src/eventsources/cron.yaml
+   type: cron
+   events:
+     cron.0 0 * * *.UTC:
+       description: Daily task at midnight UTC
+       fn: daily_update
+       args:
+         reportPath: <% mappings.report_path %>
+  ```
+   **Explanation**:
+   - The `report_path` mapping is used to dynamically define the report path for the workflow triggered by the event.
+
+---
+### Sample Yaml Workflow accessing mappings
 ```
   - id: httpbinCof_step1
     description: Hit http bin with some dummy data. It will send back same as response
@@ -47,8 +84,52 @@ Sample workflow accessing mappings object:
         gender: <% mappings.Gender[inputs.body.Gender] %>
         id:  <% mappings.generate.genId %>
 ```
+### Sample typescript Workflow accessing mappings
+
+In this example, mappings is utilized to dynamically retrieve error messages based on an error code.
+
+```
+import { GSContext, GSStatus } from '@godspeedsystems/core';
+
+export default async function(ctx: GSContext, args: any) {
+    const { mappings, childLogger, inputs } = ctx;
+      let error: any = {};
+        error.code = args?.code; 
+        error.message = args?.message;
+
+            if (!error.code) {
+                error.code = "E001";
+            } 
+            if (!error.message) {
+                error.message = mappings.error_codes.codes[error.code];
+            }
+        return new GSStatus(false, 400, undefined, error.message, undefined);
+      }
+
+```
+### Step-by-Step Explanation of above ts workflow
+
+- The mappings object is destructured from the ctx (Godspeed context).
+- In this case, mappings.error_codes.codes contains a predefined set of error codes and their corresponding messages.
+- The function checks if the args object contains an error code and a message, if the code is missing, it defaults to "E001".
+- If the message is not provided in the args, the function retrieves it from `mappings.error_codes.codes` using the error code as the key. 
+
+### Mappings file containing error codes
+`src/mappings/error_codes.yaml`
+```yaml
+  codes:
+  E001: Internal Server Error
+  E002: Missing mandatory field in the request body.
+  E003: Extra properties found in the request body.
+  E004: Wrong field type/format/pattern/length in the request body.
+  E005: Record already exists in the database.
+  E006: Record to update is not present in the database.
+  E007: Record to delete is not present in the database.
+```
+This ensures that error messages are consistent and centralized. Instead of hardcoding messages in multiple places, they are stored in the mappings file.
+
 
-## Use mappings constants in other mapping files
+## Using mapping constants in other mapping files
 You can use mapping constants in other mapping files using coffee/js scripting.
 
 For example, you have mapping files `index.yaml`, `relations.json` and `reference.yaml`. Use the mappings from first two files as reference in the third file as follows:   

docs/microservices-framework/datasources/datasource-plugins/Axios Datasource.md

@@ -35,10 +35,44 @@ import { DataSource } from '@godspeedsystems/plugins-axios-as-datasource';
 export default DataSource;
 ```
 
+### Sample config file for Axios
+
+The sample config can be modified as per the usecase of your application.
+
 ```yaml title=src/datasources/api.yaml
-type: axios
-base_url: http://localhost:4000
+  type: axios
+  base_url: https://httpbin.org
+
+  # print all api calls in curl format
+  curlifiedLogs: true 
+
+  # Authentication of API calls with token refresh logic
+  authn: 
+    fn: my_bank.authn
+    refreshOn:
+      statusCode: [401]
+
+  # Common headers to be set in all API calls
+  headers:
+    Content-Type: application/json
+    Cookie: <%mappings.my_bank.auth_workflow_cookie%>
+
+  # Retry logic for failed API calls for ex on Internal server errors or request timeouts
+  retry:
+      when: #the condition
+        status: [500, 503] # an array or single value of codes (optional). Default 500
+        message: my custom expected message for retry #And (optionally) when response has this message
+      max_attempts: 5
+      type: constant # or random, exponential
+      interval: PT15s
+      # type: exponential
+      # min_interval: PT5s
+      # max_internal: PT15s
+      # type: random
+      # min_interval: PT5s
+      # max_internal: PT15s
 ```
+Retry interval values will be based on [ISO Temporal Duration standard](https://tc39.es/proposal-temporal/docs/duration.html)
 
 ### Sample axios datasource yaml workflow
 ```yaml title=src/functions/sample.yaml
@@ -163,42 +197,7 @@ tasks:
       min_interval: PT5s
       max_internal: PT15s
 ```
-The sample config can be modified as per the usecase of your application. For example,
 
-```yaml title=src/datasources/api.yaml
-type: axios
-base_url: https://httpbin.org
-
-# print all api calls in curl format
-curlifiedLogs: true 
-
-# Authentication of API calls with token refresh logic
-authn: 
-  fn: my_bank.authn
-  refreshOn:
-    statusCode: [401]
-
-# Common headers to be set in all API calls
-headers:
-  Content-Type: application/json
-  Cookie: <%mappings.my_bank.auth_workflow_cookie%>
-
-# Retry logic for failed API calls for ex on Internal server errors or request timeouts
-retry:
-    when: #the condition
-      status: [500, 503] # an array or single value of codes (optional). Default 500
-      message: my custom expected message for retry #And (optionally) when response has this message
-    max_attempts: 5
-    type: constant # or random, exponential
-    interval: PT15s
-    # type: exponential
-    # min_interval: PT5s
-    # max_internal: PT15s
-    # type: random
-    # min_interval: PT5s
-    # max_internal: PT15s
-```
-Retry interval values will be based on [ISO Temporal Duration standard](https://tc39.es/proposal-temporal/docs/duration.html)
 ### 4. Authentication of API calls with token refresh logic
 
 HTTP requests sometimes need authentication, means they are validated against a token which is passed in the headers