Helpers and utilities
The functions that build queries, read results and parse URLs — grouped by what they are for, with the ones to avoid marked as such.
Two barrels, helpers/ and utils/, exporting about sixty functions in no particular order. Grouped here by
task, and every one of them either points at the guide that uses it or says why it is not worth using.
Building a query
| Function | What it gives you | Worth knowing |
|---|---|---|
filter.eq neq gt gte lt lte like contains regex | A SimpleFilter | The only way you should ever need to write a filter by hand |
filter.in between isNull isNotNull | InFilter, BetweenFilter, … | in with an empty array collapses to undefined, on purpose |
filter.and or not | An ExprFilter, or undefined | Falsy children are dropped; a single survivor comes back unwrapped |
filter.distribution | A range Filter | For a range facet. Passing a distribution item to filter.eq answers 500 |
addConcepts removeConcept removeConcepts getConcepts | Query text with +[concept] tokens edited | Never build the token by hand — the syntax has escaping rules |
parseText rewriteText | FullTextPattern[] ↔ string | The parser behind the above: quoted phrases, /regex/, concepts |
legacyFilterToFilter | A modern Filter from a pre-2.0 Select | For migrating stored queries. Nothing else |
Reading a result
| Function | What it gives you | Worth knowing |
|---|---|---|
resultPages(result, pageSize) | The numbers a pager renders | rowCount alone is not enough; this does the arithmetic |
getMetadata(article, field) | string[] | Reads a metadata field regardless of how the server shaped it |
getMetadataWithValues(article, field) | { display, value }[] | When you need the raw value to filter on, not only the label |
makeColumn · extraColumns | A CCColumn | Declaring a column the server configuration does not |
resolveToColumnName(alias, app, queryName?) | The real column name, or undefined | Query aliases first, then the merged index schema |
resolveAggregationCount · aggregationHasMore | The page size, and whether more remain | The server returns count + 1 items when more exist. Never compare for equality |
suggestionsToTreeAggregationNodes | TreeAggregationNode[] | Rendering a tree facet from autocomplete answers |
aggregationItemStrictCompare | boolean | Identity of two facet items — value and path, not display |
flattenLegacyFilterValues(filters) | string[] | Every leaf value/display in a LegacyFilter tree — restores $selected from a stored or URL filter |
Reading a result · Aggregations · Paging
URL state
| Function | What it gives you | Worth knowing |
|---|---|---|
getQueryParamsFromUrl(url) | QueryParams | The whole search state out of a URL, in one call |
getUrlParamsFromQueryParams(params) | URLSearchParams | The other direction. Pair them; do not hand-roll one side |
getQueryTextFromUrl · getIdFromUrl · getQueryTabFromUrl | One field | When the whole object is more than you need |
getQueryPageFromUrl(url) | number | Defaults to 0 while Query.page is 1-based. Read the pitfall first |
getFiltersFromUrl(url) | LegacyFilter[] | Legacy shapes: pass them through legacyFilterToFilter |
Dates and localisation
| Function | What it gives you | Worth knowing |
|---|---|---|
sysLang(text, locale) | One language out of an all[fr]tous[de]alle string | Server labels are multilingual; this is how you read them |
translateAggregationToDateOptions(agg) | DateFilter[] | Turns a date facet into relative-date choices |
getRelativeDate(offset) | RelativeDate | The unit is always "day" — the parameter suggesting otherwise is ignored |
Infrastructure
| Function | What it gives you | Worth knowing |
|---|---|---|
configureLogger({ level }) | Log verbosity | The only way to set it. The logLevel config key is inert |
notify.info warn error | A dispatched CustomEvent | No UI of its own — your application listens |
Audit.notify(events) | A recorded usage event | Carries noRecovery: a 401 here is never a session to repair |
escapeExpr(value) | An escaped expression fragment | Use it on anything user-typed that reaches a Sinequa expression |
toSqlValue(value) | A quoted SQL literal | Not reachable from @sinequa/atomic: src/utils/index.ts omits it while listing every sibling. Written, tested, used internally by fetchSuggest, and unimportable |
hashString(value, seed?) | A short non-cryptographic hash (cyrb53) | For cache keys and deduplication |
bisect(items, predicate) | { true: T[]; false: T[] } | Partition in one pass. Generic; nothing Sinequa about it |
Logging · Notifications · Audit
Names that mislead
Two exports whose names promise something they do not deliver. Both are still exported, so both are documented here rather than left as a surprise.
guid() is not a UUID
It is built from Math.random(). Uniqueness is not guaranteed, and it is not a v4 UUID whatever the shape
suggests. Use crypto.randomUUID() where you need either property.
sha512() throws rather than lying
It used to fall back to a repeated FNV-1a, returning a 128-character string that was the SHA-512 of nothing — a
real hazard for anyone who reached for it by name. It now throws when the platform offers no crypto.subtle,
and hashString() is the honest non-cryptographic alternative for cache keys.
Renamed
Both names still work; the old one carries the @deprecated tag, so your editor strikes it through.
| Old name | Write instead |
|---|---|
getJWToken | requestWebTokenSession |
appInitializerFn | initializeAppConfig |
fetchSuggestQuery | fetchSuggest |
isString | typeof value === "string" |
Four more are tagged as implementation details the HTTP helpers already apply on every call, so there is never a
reason to call them yourself: createHeaders (pass options.headers), handleResponse,
resolveNoAutoAuthentication (pass options.noAutoAuthentication) and withRetry.
What's next
Map of the types
Which family a type belongs to, what it relates to, and where the guide that explains it is — for the 130-odd types the library exports.
Migrating from 1.x
The one breaking change between 1.x and 2.x, the type changes that surface as compile errors, and what is worth rewriting even though it still runs.