fix(core): honest return types for Result chaining and the batch envelope, plus a type-level test gate

[IgorShevchik]

Two typing defects in 2.x, both invisible at runtime, both making callers work around a declaration that did not match the implementation — plus the test gate that makes type-level assertions in this repo mean anything.

Split out of #279: this is the half that needs no design decision.

What "non-breaking" means here, precisely

No runtime behaviour changes at all. The emitted .d.ts does change: Result.setData / addError / addErrors now return this rather than Result<T>, and IResult.addError / addErrors return IResult<T> rather than a bare IResult. Every new declaration accepts strictly more and returns strictly more precisely than the one it replaces, so a caller that chains or ignores the return value is unaffected. Someone doing an exact signature comparison against the old interface — a satisfies check, or their own class declaring addError(...): IResult — still type-checks, because IResult is IResult<any> and assignable in both directions. Calling it non-breaking is a judgement about a type-only change, not a claim that nothing moved; flagging it explicitly rather than leaving it implicit.

1. Result chaining threw the type away

IResult.addError / addErrors were declared as returning a bare IResult — that is, IResult<any>:

const data = Result.ok<Deal>({ id: 1 }).addError('boom').getData()
//    ^? any  — the payload type is gone, and a typo behind the chain compiles

The class methods returned Result<T>: right for Result, wrong for every subclass — chaining off an AjaxResult widened it back and lost getStatus() / getQuery(). Both are now the polymorphic this.

setData was declared (data: T) => … while the implementation has always accepted T | null | undefined, so clearing a result through an IResult-typed reference was a type error against code that works. (The docs page had it right and the code did not.)

2. The batch envelope was described one level too deep

AjaxResult<X> already means "the body is { result: X, time }". The batch transport passed BatchPayload<T> — itself { result, time } — so the declared shape was { result: { result: …, time }, time }.

Nothing failed, because every processing strategy laundered the difference:

const responseResult = responseHelper.response.getData()!.result as unknown as BatchResponseData<T>

Those as unknown as casts read as cosmetic and were load-bearing: they silenced a real mismatch. Worse, the old type made getData()!.result resolve to the v2 envelope even under the v3 transport, whose result is a bare array/record.

The type argument is now BatchResponsePayload<T> — the union of what the two versions actually send — and the remaining casts are plain narrowings of one of its arms. Documented alongside it: the union carries no discriminant, so the v2/v3 pairing is held by the transport, not by the type system.

3. A gate that was passing vacuously

New jsSdk:types vitest project — the only one with typecheck enabled, and it has to be. expectTypeOf is erased at runtime, so under a plain vitest run a type assertion cannot fail, and test/ sits outside every tsc pass in the repo. The existing call-params-types.unit.spec.ts was reporting as passing while checking nothing; it is renamed to call-params.types.spec.ts and now runs under the gate, with its weakest pins tightened (toMatchTypeOf<Record<string, unknown>> and not.toBeNever() both pass against any, so they proved the file compiled, not what it compiled to).

test/tsconfig.json extends the package config rather than restating a subset of its flags — strict does not imply noUnusedLocals, noImplicitReturns or noPropertyAccessFromIndexSignature, and a hand-copied set drifts silently. That inheritance runs in the unusual direction (a root-level test dir depending on a package build config), so packages/jssdk/tsconfig.json now names its second consumer at the top, and #396 tracks the proper fix — inverting it into a shared base config, which touches the build config and wants its own PR.

vitest and @vitest/ui are pinned to exact versions, because Vitest warns that this typecheck mode is experimental and may break outside semver. Dependabot covers the root manifest and rewrites exact specifiers just as it does ranges, so the pin does not become a blind spot for a security patch.

Everything verified by mutation, not assumption: reverting addError to Result<T> fails the spec; dropping either arm of the v3 filter union fails the tightened pins; an unused local fails, proving the stricter inherited flags are live.

Checks

• pnpm run typecheck — all eight passes green
• jsSdk:unit + skills:unit + jsSdk:types — 58 files, 650 tests, no type errors
• lint (1 pre-existing unrelated warning in docs/server/api/ai.post.ts, deliberately untouched), lint:md, md-internal-links, docs-lint --strict, check-api-reference-index, check-v3-method-refs
• tsc -p test/tsconfig.json --noEmit run directly — the vitest runner had been hiding a config error that only a direct invocation surfaced
• Portal-backed projects not run: no transport behaviour changed. The runtime side of the batch retyping is covered by the existing batch-null-result / batch-array-error-key / http-batch-soft-error specs, which decode real envelopes through getData() and still pass — the expression read out of it is byte-identical before and after.

Lockfile

Regenerating the lock for the pin also moved a transitive tinyexec from 1.2.4 to 1.3.0 in five blocks. That is the whole of the rest of the lockfile diff — no added or removed packages, no changed integrity hashes elsewhere — and it is the resolution vitest 4.1.10 itself asks for. Naming it so the line is not mistaken later for an unexplained lockfile edit.

Docs

70.core-result.md, 90.types-iresult.md and 90.types-payloads.md were left stale by the source change and are updated — the payloads page in particular presented BatchPayload as what a batch response decodes to, which is the exact conflation that caused the bug. .github/contributing/testing.md gains a section on the *.types.spec.ts suffix, and loses a line that had become false: it claimed CI does not run Vitest, while the test job already runs the portal-free projects.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F22e2ft66y7nuBJjzdThBr