refactor: remove ts-toolbelt dependency

[regevbr]

Summary

• Remove ts-toolbelt dependency by replacing all utilities with native TypeScript built-ins and custom implementations
• Maintain 100% type safety with no runtime behavior changes
• Reduce bundle size by eliminating the only runtime dependency

Changes

New file: src/types/utils.ts

Custom type utilities replacing ts-toolbelt:

• Primitive, BuiltIn - Type categories
• List, Cast, Keys, Compute - Any/list utilities
• Split, Join - String utilities
• Path, FilterNever, NonNullableFlat - Object utilities
• RequireOnlyOne - Replacement for Object.Either

Modified files

File	Changes
src/types/paths.ts	Replace ts-toolbelt imports with ./utils
src/types/required.ts	Replace Misc.BuiltIn → BuiltIn
src/types/evaluator.ts	Replace ts-toolbelt imports, re-export RequireOnlyOne
src/types/expressionParts.ts	Replace imports, use native Parameters
src/lib/helpers.ts	Replace Any.Key → PropertyKey
src/lib/engine.ts	Add type assertion for RuleDefinition narrowing
src/test/types/expressionParts.ts	Replace Any.Compute → Compute
package.json	Remove ts-toolbelt dependency

Test plan

• All 166 unit tests pass
• 100% code coverage maintained
• All TypeScript definition tests pass
• Linting passes
• Full CI pipeline passes (pnpm run ci)

🤖 Generated with Claude Code

[qltysh]

❌ 4 blocking issues (4 total)

Tool	Category	Rule	Count
radarlint-js	Lint	Remove this type without members or change this type intersection.	3	❌
radarlint-js	Lint	'unknown' is overridden by other types in this intersection type.	1	❌

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (2)

Rating	File	% Diff	Uncovered Line #s
	src/lib/helpers.ts	100.0%
	src/lib/engine.ts	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

[rubnogueira]

Follow-up review: type correctness, exact parity & TypeScript performance

Pushed as ae40639. This is a deep review of the ts-toolbelt removal focused on exact behavioural parity with the old types, type-check performance, and regression safety.

TL;DR — TypeScript performance (identical cross-context or logic)

Compiling the same deep cross-context { or: [a, b] } assignment (tsc --extendedDiagnostics):

Metric	OLD (ts-toolbelt)	NEW (this branch)	Δ
Result	❌ TS2321 (excessive depth)	✅ compiles	—
Types	1,018,577	61,698	~16.5× fewer
Instantiations	4,147,372	238,969	~17.4× fewer
Memory	~1,100 MB	~216 MB	~5× less
Check time	9.77 s	1.00 s	~10× faster

The TS2321: Excessive stack depth comparing types 'Path<?, P>' that surfaced downstream is reproduced by the old ts-toolbelt Object.Path — it was not introduced here; this branch removes it.

Root cause & fix — Path

ts-toolbelt's Object.Path materialised its result (_Path<..> extends infer X ? Cast<X,any>). The first cut of utils.ts dropped that boundary, so relating two Path<> instances recursed structurally through every nested step → TS2321 / TS2589 on deep contexts. Restored a materialization boundary:

type _Path<O, P extends readonly PropertyKey[]> =
  P extends [] ? O
  : P extends [infer H extends PropertyKey, ...infer T extends PropertyKey[]] ? _Path<At<O, H>, T>
  : never;
export type Path<O, P extends readonly PropertyKey[]> = _Path<O, P> extends infer X ? X : never;

I also measured the ts-toolbelt-style object-indexed iteration ({0,1}[Extends<..>]) and a per-key Path cache — both were worse or neutral (the iteration form reproduces TS2321 at ~2M instantiations; manual caching doesn't help because TS already memoises identical instantiations). The plain destructuring + materialization above is the fastest form that stays exact.

Correctness fix — deep NonNullable (ValidationContext)

The rewrite guarded recursion with O[K] extends object, which is false for SomeObject | undefined, so nullables under an optional/nullable object property were left un-stripped (a regression vs the released ts-toolbelt behaviour). Fixed by stripping null before the guard, and added src/test/types/validationContext.test-d.ts (fails on the old code, passes now).

Bot comments (radarlint S4335 / S6571) — resolved

The 4 flagged & {} / & unknown intersections are erased no-ops. Removed them; RequireOnlyOne keeps a bare homomorphic mapped-type prettify that is structurally identical to ts-toolbelt's Object.Either (strict) while staying lint-clean.

ts-toolbelt → native: old vs new (all verified Equal)

Removed ts-toolbelt usage	Replacement	Verified
Any.Key	PropertyKey	✅ exact
Any.Cast	Cast	✅ exact
Any.Keys	Keys	✅ exact
Any.Compute (ComputeRaw)	Compute (bare mapped type)	✅ exact
List.List	List	✅ exact
List.Length<P>	P['length']	✅ exact
Misc.BuiltIn	BuiltIn	✅ exact
Misc.Primitive	Primitive	✅ exact
Union.Exclude	Exclude (native)	✅ exact
Union.NonNullable	NonNullable / globalThis.NonNullable	✅ exact
Function.Parameters	Parameters (native)	✅ exact
String.Split / String.Join	Split / Join	✅ exact
Object.Path	Path (materialized)	✅ exact
Object.Either	RequireOnlyOne	✅ exact
Object.Filter<_, never, 'equals'>	FilterNever	✅ exact
Object.NonNullable NonNullableFlat	(removed — was a no-op on key tuples)	n/a

Parity method: reinstalled ts-toolbelt locally and asserted Equal<Old, New> (invariant identity, not just assignability) for the whole public surface — Expression, ExpressionParts, ValidationContext, PropertyCompareOps, StringPaths, Paths, Rule — across a battery of contexts (optional/nullable objects, arrays, tuples, Record index signatures, readonly, any/unknown, union objects, depth‑11 chains, Moment+Ignore, empty/single‑key). All identical. (ts-toolbelt is not re-added as a dependency.)

Extra optimisation

paths.ts wrapped every path leaf in NonNullableFlat<[...P, k]>; the tuple is PropertyKeys (never nullable), so it was a no-op. Dropped it (and the now-unused export) — small per-leaf instantiation + memory saving, output unchanged.

Regression guard — src/test/benchmark.spec.ts

New cross-platform benchmark: compiles a heavy fixture with tsc --extendedDiagnostics and fails if there's any excessive-depth error or instantiations regress past budget. Reverting Path to a ts-toolbelt-style encoding trips it (TS2321 + ~2M instantiations); current baseline ~321k.

Verification

lint, compile, tsd (incl. new regression test), 100% coverage (167 tests), and pnpm run ci all pass.

🤖 Generated with Claude Code

[rubnogueira]

@qltysh resume