Name Conflicts Between Categories

Name Conflicts Between Categories

helpers4 is split into independent npm packages — one per category. Each package can be installed and tree-shaken independently. A deliberate consequence of this design is that the same function name can exist in multiple categories when the operation makes sense for different data types.

This is not a bug. compact for arrays and compact for objects are genuinely different operations, and merging them into a single overloaded function would break tree-shaking and make the types less precise.

Known Conflicts

Auto-generated from the current build — always reflects the documented version.

Function	Categories
compact	array, object
compare	date, version
countBy	array, map, set
difference	array, date
equalsDeep	array, object
equalsShallow	array, object
fetchJson	fetch, promise
fetchOrThrow	fetch, promise
filter	map, set
identity	function, geometry
intersection	array, geometry
intersects	array, geometry
invert	geometry, object
isEmpty	array, object, string
isNonEmpty	array, object, string
isValid	date, version
map	object, set
parse	json, version
safeFetch	fetch, promise
stringify	json, version
toMapByKey	map, set

Resolving Conflicts

When you need two helpers with the same name in the same file, rename one (or both) at the import site using the as keyword.

Recommended naming convention

Suffix with 4{category} — consistent with the helpers4 naming identity:

import { compact as compact4array } from '@helpers4/array';
import { compact as compact4object } from '@helpers4/object';

const numbers = compact4array([0, 1, null, 2, undefined]);
// => [1, 2]

const user = compact4object({ id: 1, name: null, role: undefined });
// => { id: 1 }

All conflicts — resolution examples

compact

import { compact as compact4array } from '@helpers4/array';
import { compact as compact4object } from '@helpers4/object';

compare

import { compare as compare4date } from '@helpers4/date';
import { compare as compare4version } from '@helpers4/version';

countBy

import { countBy as countBy4array } from '@helpers4/array';
import { countBy as countBy4map } from '@helpers4/map';
import { countBy as countBy4set } from '@helpers4/set';

difference

import { difference as difference4array } from '@helpers4/array';
import { difference as difference4date } from '@helpers4/date';

equalsDeep

import { equalsDeep as equalsDeep4array } from '@helpers4/array';
import { equalsDeep as equalsDeep4object } from '@helpers4/object';

equalsShallow

import { equalsShallow as equalsShallow4array } from '@helpers4/array';
import { equalsShallow as equalsShallow4object } from '@helpers4/object';

fetchJson

import { fetchJson as fetchJson4fetch } from '@helpers4/fetch';
import { fetchJson as fetchJson4promise } from '@helpers4/promise';

fetchOrThrow

import { fetchOrThrow as fetchOrThrow4fetch } from '@helpers4/fetch';
import { fetchOrThrow as fetchOrThrow4promise } from '@helpers4/promise';

filter

import { filter as filter4map } from '@helpers4/map';
import { filter as filter4set } from '@helpers4/set';

identity

import { identity as identity4function } from '@helpers4/function';
import { identity as identity4geometry } from '@helpers4/geometry';

intersection

import { intersection as intersection4array } from '@helpers4/array';
import { intersection as intersection4geometry } from '@helpers4/geometry';

intersects

import { intersects as intersects4array } from '@helpers4/array';
import { intersects as intersects4geometry } from '@helpers4/geometry';

invert

import { invert as invert4geometry } from '@helpers4/geometry';
import { invert as invert4object } from '@helpers4/object';

isEmpty

import { isEmpty as isEmpty4array } from '@helpers4/array';
import { isEmpty as isEmpty4object } from '@helpers4/object';
import { isEmpty as isEmpty4string } from '@helpers4/string';

isNonEmpty

import { isNonEmpty as isNonEmpty4array } from '@helpers4/array';
import { isNonEmpty as isNonEmpty4object } from '@helpers4/object';
import { isNonEmpty as isNonEmpty4string } from '@helpers4/string';

isValid

import { isValid as isValid4date } from '@helpers4/date';
import { isValid as isValid4version } from '@helpers4/version';

map

import { map as map4object } from '@helpers4/object';
import { map as map4set } from '@helpers4/set';

parse

import { parse as parse4json } from '@helpers4/json';
import { parse as parse4version } from '@helpers4/version';

safeFetch

import { safeFetch as safeFetch4fetch } from '@helpers4/fetch';
import { safeFetch as safeFetch4promise } from '@helpers4/promise';

stringify

import { stringify as stringify4json } from '@helpers4/json';
import { stringify as stringify4version } from '@helpers4/version';

toMapByKey

import { toMapByKey as toMapByKey4map } from '@helpers4/map';
import { toMapByKey as toMapByKey4set } from '@helpers4/set';

Alternative: namespace import

If you use many helpers from both conflicting categories, a namespace import is more concise — but check that your bundler handles namespace tree-shaking (esbuild, Rollup, and Vite all do):

import * as A from '@helpers4/array';
import * as O from '@helpers4/object';

A.compact([0, 1, null]);
O.compact({ a: 1, b: null });

Note

Prefer named as imports for maximum tree-shaking compatibility with all bundlers, including older Webpack 4 configurations.

What about a single unified package?

Two “install everything” options exist, and neither reintroduces the naming collision:

• @helpers4/all is a documentation-only bundle: it lists every category as a peerDependency but ships no code of its own, so there is no flat module where two same-named exports could collide — you still install and import each @helpers4/<category> package directly.
• helpers4 (added in v3.1.0) installs every category as a real dependency in one npm install helpers4, but keeps the per-category split at the import site: each category is reachable only at its own subpath (helpers4/array, helpers4/object, …). There is no top-level import ... from 'helpers4' — since only the subpaths resolve, compact from array and compact from object never share a module and can never collide.

Both forms are equivalent — helpers4/<category> re-exports @helpers4/<category> verbatim, so the same as rename above works no matter which one you installed:

import { compact as compact4array } from 'helpers4/array';
import { compact as compact4object } from 'helpers4/object';

Design rationale

See Philosophy — Category independence for a deeper explanation of why cross-category deduplication is intentionally avoided.