Utilities & Helpers

Shared functions live in libs/shared/src/, split across a few folders:

Folder	What's in it	Import from
utils/	Formatters, date/number helpers, downloads, graph-data builders	@aquagen-mf-webapp/shared/utils
helper/	Navigation singletons and other stateful helpers	@aquagen-mf-webapp/shared/helper
hooks/	Reusable React hooks	@aquagen-mf-webapp/shared/hooks/<file>

Import rules — read first

• Import from subpaths, not the bare root. @aquagen-mf-webapp/shared points at a missing file and won't resolve.
• The folder is helper (singular) and utils (plural).
• Most utils export a class/namespace object, not loose functions. You call methods on it: DateFormatter.formatter(...), Download.PDF(...), Formatter.valueFormatter(...).
• hooks/ has no barrel — import each hook by its file path.

The aliases are defined in tsconfig.base.json:

"@aquagen-mf-webapp/shared/*": ["libs/shared/src/*"]

---

Utils (utils/)

Most of these are exported as a named namespace object (export { Download }) and used by calling methods on it. The utils/index.js barrel re-exports most files, so import { X } from '@aquagen-mf-webapp/shared/utils' works for them.

Import name	File	What it's for	Real methods / exports
DateFormatter	dateFormatter.js	Format & manipulate dates	.formatter, .customFormatter, .convertToMoment, .stringToDate, .getDateObject, .getStartDate, .isSame, .checkIsSameOrBefore
Formatter	formatter.js	Format numbers/values	.valueFormatter, .formatNumber, .defaultValue, .safeNumber
Download	downloadUtil.js	Export files	.PNG, .PDF, .EXCEL
handleNavigationOnResponse	navigationHelper.js	Route after an API response (a plain function)	—
(functions)	graphData.js	Build chart datasets	getBarGraphData, getPieChartData, getLineGraphData, getDashboardLineGraphData, getTotalGraphData, …
LabelData	labelData.js	Build chart axis/legend labels	namespace object
GetParamsData	getParams.js	Read URL params	namespace object
getParams	paramHelper.js	Read URL params (function)	—
OtpLoginCheck	otpLoginChecks.js	Validate phone/OTP inputs	namespace object
NotificationService	notificationUtil.js	Browser notifications	namespace object

Not in the barrel — import by file path:

Import name	Subpath
GraphUtil	@aquagen-mf-webapp/shared/utils/graphUtil
validateUrl, isUrlSafe, sanitizeImageUrl, …	@aquagen-mf-webapp/shared/utils/urlValidator

note

numberUtils.js exists but is empty — it exports nothing. Number formatting lives in Formatter (formatter.js).

Examples

import { DateFormatter, Formatter } from '@aquagen-mf-webapp/shared/utils';

const label = DateFormatter.formatter(apiDate);      // format a date
const date  = DateFormatter.stringToDate('2026-07-21');
const value = Formatter.valueFormatter(12345.67);    // format a number

import { Download } from '@aquagen-mf-webapp/shared/utils/downloadUtil';

Download.PDF(...);     // export a PDF
Download.EXCEL(...);   // export an Excel file
Download.PNG(...);     // export an image

import { handleNavigationOnResponse } from '@aquagen-mf-webapp/shared/utils';

handleNavigationOnResponse(response, setLoginData, setCategory, navigate);

---

Helpers (helper/)

These are navigation helper singletons — each exposes an .instance you use for programmatic navigation and route logic within its area of the app.

Import name	File	Scope
NavigationHelper	navHelperInstance.js	App-wide navigation
EnergyNavigationHelper	energyNavigationHelperInstance.js	Energy module
ExecutiveNavigationHelper	executiveNavigationHelperInstance.js	Leadership/executive views
LakePulseNavigationHelper	lakePulseNavigationHelperInstance.js	Lake Pulse app
UwmsNavigationHelper	uwmsNavigationHelperInstance.js	Aqua Recycle (uwms) app
RwiNavigationHelper	rwiNavigationHelperInstance.js	RWI app (not in barrel)
AlertsHelper	alertHelperInstance.js	Alert filtering/sorting (not in barrel)
SubscriptionHelper	subscriptionHelper.js	Subscription status (not in barrel)

The helper/index.js barrel re-exports only the first five. The three marked not in barrel must be imported by file path.

// From the barrel:
import { NavigationHelper } from '@aquagen-mf-webapp/shared/helper';
NavigationHelper.instance.navigate('/dashboard');

// Not in the barrel — use the file subpath:
import { AlertsHelper } from '@aquagen-mf-webapp/shared/helper/alertHelperInstance';
import { SubscriptionHelper } from '@aquagen-mf-webapp/shared/helper/subscriptionHelper';

---

Hooks (hooks/)

There is no hooks/index.js — import each hook from its own file: @aquagen-mf-webapp/shared/hooks/<fileName>.

Hook	File	Export
useNavigateSearchParams	useNavigateSearchParams.js	default
useQueryParams	useQueryParams.js	named
useScrollToElement	useScrollToElement.js	default
useLineGraphToggle	useLineGraphToggle.jsx	default
useNavigateToUnit	useNavigateToUnit.js	default
usePageTypeCheck	usePageTypeCheck.js	default
useRenderElement	useRenderElement.jsx	default
useSearchParamsHook	useSearchParamHook.js	default
useSendMail	useSendMail.js	named
useSubscriptionProposalHook	useSubscriptionProposalHook.js	named

import useNavigateSearchParams from '@aquagen-mf-webapp/shared/hooks/useNavigateSearchParams';
import { useQueryParams } from '@aquagen-mf-webapp/shared/hooks/useQueryParams';

const navigateSearch = useNavigateSearchParams();
const params = useQueryParams();

Watch the names

• The hook is useNavigateSearchParams (not useNavigateSearch) — it's the most-used hook in the app.
• useSearchParamHook.js (singular file) exports useSearchParamsHook (plural).
• useNavigateToQueryParams.js currently default-exports the identifier useNavigateSearchParams — a known copy-paste mismatch; prefer useNavigateSearchParams.js.

---

Gotchas

• Class-object pattern: call methods on the imported object (Formatter.valueFormatter(x)), don't destructure functions that don't exist.
• Barrel gaps: utils omits graphUtil and urlValidator; helper omits alertHelperInstance, subscriptionHelper, rwiNavigationHelperInstance. Import those by file path.
• Export name ≠ file name for helpers: navHelperInstance.js exports NavigationHelper, alertHelperInstance.js exports AlertsHelper, etc.
• numberUtils.js is empty — don't import from it.

---

Next Steps

• Components — the shared UI components these utilities support
• API & Services — the API/service layer
• Commands Reference — creating and wiring up shared libraries