# EC React Utils Utils for the Socotra Insurance Suite [#utils-for-the-socotra-insurance-suite] This package provides a collection of shared helper functions used throughout the Socotra EC ecosystem. These utilities handle common tasks such as data extraction, transformation, default value generation, and building API requests, serving as a foundational layer for the component and application logic. The library is organized by function, including: * **Data Extraction:** Functions for safely extracting nested data from large, complex objects. * **Default Value Getters:** Functions for generating default values for forms. * **API Request Builders:** Functions for mapping form data to API request payloads. * **Miscellaneous Helpers:** A variety of other useful functions for data manipulation and comparison. *** Installation [#installation] ```sh npm i @socotra/ec-react-utils ``` This package has peer dependencies on `@socotra/ec-react-schemas` and `zod`, which you likely have installed already. *** Usage [#usage] Import any utility directly from the package: ```ts import { extractElementByType } from '@socotra/ec-react-utils'; const element = extractElementByType(quote, 'my_element_type'); ``` Documentation [#documentation] The documentation for this package is generated from a script that must be run after the package is built. To contribute to the documentation, clone the repo and run the following command: ```sh git clone https://github.com/socotra/ec-react.git cd ec-react/packages/docs/src/utils ``` Edit files under the `utils` directory. Run `pnpm run sync` to update the documentation in the `README.md` files of the other packages. Follow instructions in the `ec-react/packages/docs/README.md` file to build the documentation and update the `Socotra Documentation` repo. Available Utilities [#available-utilities] Data Extraction [#data-extraction] | Function | Description | Returns | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------- | | `getAccountEvaluatedConstraintsRequest` | Creates a request payload to evaluate constraints for an account. | `AccountEvaluateConstraintsRequest` | | `extractElementByLocator` | Extracts the first element from a policy, quote, or transaction segment that matches the specified locator. | `Element` or `undefined` | | `extractElementByType` | Extracts the first element from a policy, quote, or transaction segment that matches the specified type. | `Element` or `undefined` | | `extractElementsByType` | Extracts all elements from a policy, quote, or transaction segment that match the specified type. | `Element[]` | | `extractElementDataModelFromQuote` | Extracts the data model for a specific element type from a quote response. | `object` or `undefined` | | `extractElementDataModelFromSegment` | Extracts the data model for a specific element type from a transaction segment. | `object` or `undefined` | | `extractElementDataModelFromType` | Extracts the data model for a specific element type from a policy response. | `object` or `undefined` | | `extractElementsFromQuote` | Extracts all elements from a quote’s exposures. | `Element[]` | | `extractElementsFromTransactionSegment` | Extracts all elements from a transaction segment’s exposures. | `Element[]` | | `extractProductDataModel` | Extracts the data model for a specific product from a policy or quote. | `object` or `undefined` | | `extractProductElements` | Extracts all elements associated with a product from a policy or quote. | `Element[]` | | `shouldEvaluateConstraints` | Checks if the constraints should be evaluated based on the original and new data. | `boolean` | Default Value Getters [#default-value-getters] | Function | Description | Returns | | ---------------------------------------- | ------------------------------------------------------------------------------- | -------- | | `getCoverageTermsDefaultValues` | Generates default values for coverage terms based on the product configuration. | `object` | | `getDefaultAccountFormValues` | Generates default values for the account form. | `object` | | `getDefaultDraftTransactionValues` | Generates default values for a new draft transaction form. | `object` | | `getDefaultElementValues` | Generates default values for an element based on its data model. | `object` | | `getDefaultInitializedTransactionValues` | Generates default values for an initialized transaction form. | `object` | | `getDefaultPolicyValues` | Generates default values for a new policy. | `object` | | `getDefaultQuoteValues` | Generates default values for a new quote. | `object` | API Request Builders [#api-request-builders] | Function | Description | Returns | | ----------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------ | | `getAccountRequest` | Transforms form data into a request payload for creating or updating an account. | `AccountCreateRequest` or `AccountUpdateRequest` | | `getElementRequest` | Transforms form data into a request payload for creating or updating an element. | `ElementCreateRequest` or `ElementUpdateRequest` | | `getEvaluatedConstraintsRequest` | Creates a request payload to evaluate constraints for a specific element. | `EvaluateConstraintsRequest` | | `getModifyChangeInstructionCreateRequestFromFormData` | Transforms form data into a request to modify a transaction’s change instructions. | `ModifyChangeInstructionCreateRequest` | | `getParamsChangeInstructionCreateRequestFromFormData` | Transforms form data into a request to update the parameters of a transaction. | `ParamsChangeInstructionCreateRequest` | | `getElementTransactionUpdateRequestFromFormData` | Transforms form data into a request to update an element within a transaction. | `ElementTransactionUpdateRequest` | | `getPolicyRequest` | Transforms form data into a request payload for creating a new policy. | `PolicyCreateRequest` | | `getQuoteRequest` | Transforms form data into a request payload for creating or updating a quote. | `QuoteRequest` | Miscellaneous [#miscellaneous] \| Function | Description | Returns | \| ------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------- | ------ | -------- | \| `compareData` | Compares two data objects and returns a list of differences. | `Diff[]` | \| `dataModelToJSONSchema` | Converts a Socotra data model into a JSON schema for form generation. | `JSONSchema7` | \| `getElementNameByType` | Retrieves the display name of an element based on its type from the product configuration. | `string` | \| `getRemoveDataFieldValues` | Identifies fields that should be removed from a data object based on a comparison. | `object` | \| `getUpdatedDataFromConstraints` | Applies the results of a constraint evaluation to a data object. | `object` | \| `parseToPrimitive` | Safely parses a string into a boolean, number, or returns the original string. | `string | number | boolean` | \| `splitInputAndQuantifier` | Splits a string into its core name and a quantifier suffix (e.g., `?`, `*`). | `{ name: string; quantifier: string }` | \| `translateError` | Translates a validation error object into a human-readable string. | `string` | Documentation [#documentation-1] The documentation for this package is generated from a script that must be run after the package is built. To contribute to the documentation, clone the repo and run the following command: ```sh git clone https://github.com/socotra/ec-react.git cd ec-react/packages/docs/src/utils ``` Edit files under the `utils` directory. Run `pnpm run sync` to update the documentation in the `README.md` files of this package. Run `pnpm run build` to build the documentation for the `Socotra Documentation` repo. Follow instructions in the `ec-react/packages/docs/README.md` file to build the documentation and update the `Socotra Documentation` repo.