Useful Utils

esw-utils is the shared utility package every Host and Remote already depends on. It collects the small, fiddly helpers you'd otherwise rewrite on every screen — form validation, notifications, list add/update/remove, OData filters, JSON parsing — into one place, tested and consistent.

Reach for these before writing custom code (Rule 13 in Template Rules). If a helper here covers what you need, use it; don't reimplement it.

How to use

The helpers are exposed through the project's helper composable at src/composables/use-helper.ts (a Host keeps its shared one under src/composables/shared/use-helper.ts). It's auto-imported — destructure what you need, no import line required:

// the composable exported from src/composables/use-helper.ts
const { validateAllSchema, notif, replacerData } = useHelper()

That composable simply spreads in esw-utils's useUtils(). To pull from the source directly instead:

import { useUtils } from 'esw-utils'

const { validateSchema, filterOrIn } = useUtils()

Notifications

Helper	Signature	Description
notif	notif(options): Promise<void>	One unified notification for success / info / warning / error / promise. Optional routing + redirect; non-error toasts auto-dismiss (~3s).

Schema validation (Yup)

Helper	Signature	Description
validateAllSchema	validateAllSchema({ schema, input, error }, cb?): Promise<boolean>	Validate a whole form object against a Yup schema (nested objects supported). Fills the error object with per-field messages + validity.
validateSchema	validateSchema({ schema, field, input, error }, cb?): Promise<boolean>	Validate a single field. Updates that field's message + valid flag in the error object.
validateAllSchemaCheck	validateAllSchemaCheck(error): boolean	Quick check — true if any field in the error object is currently invalid.
clearSchemaValidation	clearSchemaValidation({ error })	Recursively reset all errors — valid = true, message = ''.

Data manipulation & filtering

Helper	Signature	Description
replacerData	replacerData({ fn, type, item, key, items })	Add / update / remove a row in an array or a DevExtreme DataSource. type picks the target — data (array) or datasource; fn is the op — push (prepend), replace (upsert), or remove. Strips @odata.context / @odata.url metadata on the datasource path.
filterOrIn	filterOrIn(field, values, combine?)	Build an OData filter from a list of values — compact [field, 'in', [...]], or a chained (field = a) or (field = b) form. Returns null when there are no values.
dxFilterToString	dxFilterToString({ filter, encode? })	Convert a DevExtreme filter object to an OData v4 $filter string. Handles and/or, comparisons (eq/ne/gt…), and contains/startswith/endswith. Optional URL encoding.

DevExtreme UI helpers

Helper	Signature	Description
preventMinus	preventMinus()	Block the minus sign on numeric fields — ASCII - and Unicode −, via keydown and paste. Returns { onKeyDown, onPaste }.
numColTemplate	numColTemplate()	Auto-numbering column for DataGrids — row numbers that respect pagination, with sort/filter/edit/export disabled.

JSON & misc utilities

Helper	Signature	Description
isDate	isDate(value): value is Date	Type guard — true for a valid Date or a parseable date string/number.
isJSONString	isJSONString({ input, strict?, root? })	Check whether a string is valid JSON. Optional strict/lenient mode and a root filter (array / object / primitive).
safeJSONParse	safeJSONParse(str): any	Parse JSON with fallbacks for double-wrapped strings and error arrays like [System.Exception: {...}]. Returns null on failure.

Fetching lives elsewhere

esw-utils also has fetching / datasource-building helpers, but in these template apps data access goes through mono-utils/fetching — see Data Fetching and DataSource. This page only covers the value-add helpers above; see Template Rules (Rule 13) for the when-to-use-them rule.