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
filter	map, set
isEmpty	array, object, string
isNonEmpty	array, object, string
map	object, set
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';

filter

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

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';

map

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

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.