Client API: affected-items tuples, test coverage, and dependency/tooling updates (v4.4.30)

This release formalizes the client API change to return "affected-items" tuples, removes a legacy Express response workaround, and consolidates a number of dependency, tooling, and test-environment updates. The work here is focused on aligning types and documentation with the new action/allAction return shapes, adding unit tests that validate the updated behavior, and stabilizing build/test tooling and dependency resolution for reproducible installs and CI runs.

New Features

• Document and type affected-items tuples for actions
  • Action and allAction APIs now explicitly return a tuple: [primaryResult, affectedItems]. Affected items are typed as arrays of primary keys, composite keys, or location-key arrays where applicable.
  • Type changes applied across client API surfaces to reflect the tuple return: src/ClientApi.ts, src/CItemAPI.ts, src/PItemAPI.ts and the operation modules (src/ops/action.ts, src/ops/allAction.ts).
  • Documentation updated in docs/public/api-reference.md with examples and guidance for processing the second tuple element.
  • Rationale: make it explicit in the public API and TypeScript types when operations also report indirectly-affected items so callers can handle and surface that data reliably.

Improvements

• Remove Express empty-object workaround from allAction

  • The previous special-case that converted a server-side empty object ({}) into a tuple [[], []] and emitted a warning log was removed from src/ops/allAction.ts.
  • allAction now destructures the response directly and relies on the server to provide the expected shape. This simplifies the operation code path and removes noisy logging tied to a specific server edge case.
  • Tests were added to document and assert the new handling (see Tests section).

• Dependency and lockfile bumps

  • Bumped runtime Fjell packages to newer patch/minor versions in package.json and package-lock.json, including @fjell/core, @fjell/http-api, @fjell/logging, and @fjell/registry.
  • package-lock.json normalized to ensure deterministic installs: updated resolved tarballs, integrity fields, and removed duplicated/inconsistent entries for the bumped packages.

• Tooling and build behavior

  • Pin esbuild to exact version 0.25.9 where needed and add npm overrides to force a single esbuild version across the repository. This addresses a previously observed esbuild mismatch during docs/build.
  • GitHub Actions updated to run npm ci for reproducible installs.
  • package.json entries and formatting normalized (ensured trailing newline at EOF in several commits).

• ESM + build/test configuration changes

  • package.json now favors ESM-style exports (module + exports mapping) and points types to ./dist/index.d.ts.
  • tsconfig.json adjusted for ESM output: sourceMap enabled, outDir set to dist, declaration: true, target/module set to ES2022. Simplified compiler options and exclude lists.
  • vitest and test setup simplified and made Node-friendly (see Testing Improvements).

Tests

• Unit tests added for allAction

  • New file tests/ops/allAction.test.ts exercises the updated allAction behavior and verifies interactions with the Utilities helper methods.
  • Tests include:
    • normal tuple response handling
    • behavior when the server returns an empty object (edge-case asserted against the new expectation rather than performing an automatic conversion)
    • array responses and verification that utilities (verifyLocations, getPath, validatePK, processArray) are invoked as expected
  • These tests codify the deliberate decision to stop normalizing {} to [[], []] within the client and to verify callers and servers agree on response shapes.

• Test environment polyfills and mocking

  • tests/setup.ts now provides Node fetch/FormData/Blob/File polyfills (using undici and node:buffer) to support test code that uses these globals.
  • Reworked test dependencies to remove jsdom and @types/node; added undici and vitest-fetch-mock for fetch mocking in Vitest.
  • Vitest configuration simplified; globals:true is enabled and some coverage/test settings were removed to reduce sprawl.

Bug Fixes

• esbuild version conflict fixed
  • Pinning esbuild and adding npm overrides resolves CI failures caused by multiple esbuild versions being installed across packages.
  • This change prevents inconsistent builds of the docs and other artifacts that rely on esbuild.

Documentation Updates

• API reference updated for affected-items tuples

  • docs/public/api-reference.md updated to describe the new tuple return for action/allAction and related location-aware variants, with examples and guidance for handling affected items.
  • Examples and type signatures in the docs and in TypeScript sources were aligned.

• Local docs script change

  • docs/package.json: replace "npx copy-docs" with an explicit node invocation of the local @fjell/docs-template script to avoid npx resolution variability in different environments.

Developer Experience / CI

• npm ci in GitHub Actions

  • CI workflows changed to use npm ci for reproducible installs.

• Workflow triggers and Node version handling

  • Simplified test workflow triggers to reduce unnecessary CI runs and dropped an explicit pinned node-version from the test workflow to rely on runner defaults.

Breaking Changes / Compatibility Notes

• Response-shape expectations: client no longer normalizes {} -> [[], []]

  • Client code now expects the server to return a consistent shape for action/allAction responses. If a server returns {} (an empty object) callers should expect that exact value unless the server is updated to return the documented tuple shape.
  • If integrations or servers previously relied on the client to convert {} into [[], []], those servers or consumers must be updated to provide/handle the documented tuple shape explicitly.

• Type updates

  • Type definitions for action/allAction and location-aware variants have changed to include the second tuple element (affected items). TypeScript consumers should recompile to see and adopt the updated signatures.

Files and areas touched (representative)

• src/ops/allAction.ts — removed Express empty-object workaround and simplified response destructuring
• src/ClientApi.ts, src/CItemAPI.ts, src/PItemAPI.ts — type updates to include affected-items tuples
• docs/public/api-reference.md — documentation for affected-items tuples and examples
• tests/ops/allAction.test.ts — new unit tests covering response shapes and utilities interactions
• package.json & package-lock.json — dependency bumps, ESM export adjustments, and formatting normalization
• tests/setup.ts, vitest.config.ts, tsconfig.json — test and build configuration changes
• docs/package.json — pinned local docs-template usage

Migration guidance

• Update servers/integrations to return the documented tuple shape for action/allAction responses when applicable: [primaryResult, affectedItems].
• Re-run TypeScript compilation in consumer projects to pick up updated action/allAction signatures.
• If CI previously failed due to esbuild version mismatch, ensure npm ci is used in CI and that overrides are respected by your package manager.

If any custom code relied on the old client-side normalization of empty-object responses, update that code or the server to provide the documented tuple so callers receive a predictable response shape.