EC React Utils

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

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

Import any utility directly from the package:

import { extractElementByType } from '@socotra/ec-react-utils';

const element = extractElementByType(quote, 'my_element_type');

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:

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

Data Extraction

Function	Description	Returns
`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[]`

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

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

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

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:

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.