docs: mappers util PTL-1695

docs/001_develop/03_client-capabilities/014_utility-methods/05_mappers-util.mdx

@@ -0,0 +1,101 @@
+---
+title: 'Data Mapping Utilities'
+sidebar_label: 'Data Mapping Utilities'
+id: mappers-utils
+keywords: [utils, utility, data, decorators, env, environment, formatters, number, date, logger, logging, mappers, mixins, observers, resource, server, serializer, json, styles, css, UUID, unique, window, iframe]
+tags:
+  - utils
+  - utility
+  - data
+  - decorators
+  - env
+  - environment
+  - formatters
+  - number
+  - date
+  - logger
+  - logging
+  - mappers
+  - mixins
+  - observers
+  - resource
+  - server
+  - serializer
+  - json
+  - styles
+  - css
+  - UUID
+  - unique
+  - window
+  - iframe
+---
+
+This section describes utilities designed to simplify the conversion between different data representations within an application, with a particular focus on server row data transformations. These utilities offer a systematic approach to managing data conversions between Data Transfer Objects (DTOs) and entities, ensuring consistency and maintainability.
+
+:::info
+For more detailed information on API and configurations, please refer to the [API documentation](docs/api/index.md).
+:::
+
+## Key Components
+
+- **ServerRowDTO** - Specifies the structure for server row data as exchanged with the backend. The DTO adheres to a convention of using uppercase keys.
+- **ServerRowEntity** - Represents the client-side or application-side structure for server row data, adhering to a convention of using lowercase keys.
+- **ServerRowDTOMapper** - A specialized interface extending `DTOMapper`, designed specifically for mapping between `ServerRowDTO` and `ServerRowEntity`.
+
+## DTOMapper Interface
+
+The `DTOMapper` interface defines the core methods required for data transformation between DTOs and entities. These methods include:
+
+- **`fromDTO`** - Transforms a DTO instance into its corresponding entity representation.
+- **`toDTO`** - Converts an entity instance back into its DTO format.
+
+By leveraging these utilities, developers can achieve a clear separation of concerns and streamline data processing workflows between backend systems and the application.
+
+## DefaultServerRowDTOMapper Class
+
+The `DefaultServerRowDTOMapper` class provides a concrete implementation of the `ServerRowDTOMapper` interface, delivering robust methods to handle conversions between `ServerRowDTO` and `ServerRowEntity` seamlessly.
+
+### Conversion Methods
+
+- **`fromDTO(dto: ServerRowDTO): ServerRowEntity`**: Transforms a `ServerRowDTO` instance into a `ServerRowEntity`. This process involves converting keys from uppercase to lowercase while maintaining data integrity.
+- **`toDTO(entity: ServerRowEntity): ServerRowDTO`**: Converts a `ServerRowEntity` back into its `ServerRowDTO` representation, translating keys from lowercase to uppercase.
+
+### Usage Example
+
+Below is an example demonstrating the usage of `DefaultServerRowDTOMapper` in a typical application:
+
+```typescript
+import { ServerRowDTOMapper } from '@genesislcap/foundation-utils';
+import { GenesisElement } from '@genesislcap/web-core';
+
+export class MyExampleComponent extends GenesisElement {
+  @ServerRowDTOMapper dtoMapper!: ServerRowDTOMapper; // DI token
+
+  private dtoMapper: ServerRowDTOMapper = new DefaultServerRowDTOMapper();
+
+  private serverRowDTO: ServerRowDTO = {
+    DETAILS: {
+      OPERATION: 'INSERT',
+      ROW_REF: '12345',
+    },
+  };
+
+  connectedCallback() {
+    super.connectedCallback();
+
+    const serverRowEntity = dtoMapper.fromDTO(serverRowDTO);
+    console.log(serverRowEntity); // Outputs the entity representation
+
+    const backToDTO = dtoMapper.toDTO(serverRowEntity);
+    console.log(backToDTO); // Outputs the original DTO representation
+  }
+}
+```
+
+This example illustrates how the `DefaultServerRowDTOMapper` can be utilized to handle seamless conversions, enabling consistent data representation across different application layers.
+
+## Considerations
+
+- Utilize the provided mapper utilities for all server communication involving server row data to ensure consistency in data handling.
+- Extend the `DTOMapper` interface for other data types as needed, maintaining a uniform approach to data conversion across your application.
+- Leverage dependency injection for accessing mapper instances, enhancing modularity and testability.