Skip to content

Simplify logging and error output; dependency bumps and release 4.4.68

Choose a tag to compare

View all tags
released this 12 Dec 19:45
· 13 commits to working since this release
v4.4.68
64d2ebc

Overview

This release focuses on simplifying logging behavior inside the client API, reducing brittle, exact-match log/error assertions in tests, and publishing a stable package version. The three visible threads are (1) removal of verbose, per-level JSON logger implementations in source, (2) removal of long-form error-logging and thrown message payloads in a find operation, and (3) package metadata changes that include a version bump and small dependency updates. These changes are defensive: they reduce tightly-coupled log/error shapes embedded in the code and tests, and prepare the package metadata for a non-prerelease publish.

Key commits: fee93da (logging/tests/error cleanup), 917c606 (dependency bumps), 8a73932 (version bump to 4.4.68).

Breaking / Behavioral changes

  • Standardize and simplify final failure logging in HttpWrapper (see src/http/HttpWrapper.ts) (commit fee93da).

    • What changed: the final failure message was standardized to "${operationName} failed after all retry attempts" and the emitted fields were adjusted to include operation, errorCode, errorMessage, errorType, isRetryable, totalAttempts, duration, plus any provided context. The previously embedded retryConfig and long suggestion text were removed (commit fee93da).
    • Why it matters: callers or tools that parse log text or expect the previous suggestion/retryConfig fields will no longer find them. Logs remain structured but carry a smaller, more predictable payload.
    • What to do: stop relying on exact error/suggestion text in logs; if instrumentation needs retryConfig or suggestion details, capture them before logging or add explicit instrumentation points.

  • Error output for find operations no longer contains the previously verbose logger.error blocks and long-form thrown messages (see src/ops/find.ts) (commit fee93da).

    • What changed: detailed logger.error calls and expanded thrown error strings for invalid response shapes and non-array items were removed (commit fee93da).
    • Why it matters: code that depended on exact error message text will break; tests that asserted an exact message must be loosened.
    • What to do: match errors with regexes or test the semantic condition rather than comparing the full error string. The updated test in tests/ops/find.edge-cases.test.ts switches to a regex-based expectation (see example below).

New features

  • None in this release. Changes are behavioral and infrastructural (logging, error messaging, packaging).

Improvements and rationale (analysis)

  • Reduce logging surface area to avoid brittle contracts between code and tests (commit fee93da).

    • Evidence: src/http/HttpWrapper.ts had inline, verbose per-level JSON logging that exposed many fields and textual suggestions; those implementations were removed and replaced with a smaller structured-logger placeholder (commit fee93da).
    • Why: tests were asserting exact log payloads (many expect(...).toHaveBeenCalledWith(...) checks in tests/http/HttpWrapper.test.ts). Those assertions are brittle and tie tests to textual log structure. By simplifying the logger surface the implementation reduces churn in tests when log payloads change.
    • Implication: logging remains available, but consumers should treat log payloads as observation artifacts rather than stable API. Tests have been updated accordingly (see Tests/Developer Experience).

  • Simplify find operation error handling (commit fee93da).

    • Evidence: the code that validated response shapes in src/ops/find.ts previously threw short errors, then briefly added verbose logger.error and long thrown messages; the commit removed the verbose logger.error blocks and long-form throws (commit fee93da).
    • Why: long, narrative error strings embed implementation hints and can leak internal suggestions. Removing them reduces surface area and keeps thrown errors concise.
    • Implication: downstream code should not parse or rely on the exact wording of thrown messages from find; rely on error types/codes or use pattern matching against the message when needed.

Tests / Developer experience

  • Relaxed logging assertions in tests to prevent brittleness (commit fee93da).
    • What changed: many assertions that required exact log payloads (expect(...).toHaveBeenCalledWith(...)) were removed or replaced with looser checks (e.g., ensure the logger was called or use regex checks). Examples from tests/http/HttpWrapper.test.ts and tests/ops/find.edge-cases.test.ts reflect this change (commit fee93da).
    • Why: exact-match log assertions tied tests to the logger's internal shape; with logging simplified, tests now validate behavior (requests, retries, error propagation) rather than exact log formatting.
    • What to do: if you maintain tests that assert on logs, update them to assert that logging occurred or inspect a small, stable subset of fields rather than the full JSON payload.

Files changed (high level)

  • src/http/HttpWrapper.ts — simplified logger declaration and standardized final failure logging (commit fee93da).
  • src/ops/find.ts — removed verbose logger.error blocks and long-form thrown messages for invalid responses (commit fee93da).
  • tests/http/HttpWrapper.test.ts — removed/relaxed many exact log payload assertions (commit fee93da).
  • tests/ops/find.edge-cases.test.ts — updated error expectations to use a regex-based match rather than exact string (commit fee93da).
  • package.json — version bumped to 4.4.68 and dependency updates (see next section) (commits 8a73932, 917c606).

Dependency and packaging changes

  • Bump package version to 4.4.68 (remove -dev snapshot) (commit 8a73932).

    • Implication: this marks a stable semver release; registries and downstream consumers will resolve 4.4.68 instead of a prerelease.
    • Action: CI/publish pipelines and lockfiles should be regenerated to match the released version.

  • Dependency updates in package.json (commit 917c606):

    • Bumped patch versions: @fjell/core ^4.4.72 → ^4.4.73, @fjell/http-api ^4.4.62 → ^4.4.63, @fjell/registry ^4.4.80 → ^4.4.81.
    • Added runtime dependencies: @fjell/logging ^4.4.65 and deepmerge ^4.3.1.
    • Why it matters: adding @fjell/logging and deepmerge to runtime dependencies means they will be installed for consumers and may affect bundle size and resolution. The codebase in this commit removed inline verbose logging and left a smaller logger surface — adding @fjell/logging suggests a consolidation of logging responsibilities at the package level, but the current change only updates package.json (commit 917c606). Consumers should run CI with the updated lockfile to ensure no resolution issues.
    • Action: regenerate lockfile (package-lock.json / yarn.lock), run CI and smoke tests, and check bundles for size/regression implications.

Migration notes and examples

  • If your code or tests asserted exact log messages or payloads, update them to be resilient to message changes. Example change applied in tests/ops/find.edge-cases.test.ts (commit fee93da):

Before (exact string match):

expect(find("testFinder", {}, []))
.rejects.toThrow("Invalid response: expected FindOperationResult object");

After (regex / more tolerant):

expect(find("testFinder", {}, []))
.rejects.toThrow(/Invalid response.*expected FindOperationResult/);

  • If your observability or automation parsed suggestion text or retryConfig from logs, switch to one of:
    • record retryConfig earlier in an instrumentation event, or
    • add structured instrumentation hooks that export the fields you need (do not parse human-readable log strings).

Notes and recommended follow-ups

  • Regenerate and commit the lockfile (package-lock.json or yarn.lock) and run CI to ensure the bumped dependencies and new runtime packages do not introduce resolution or runtime issues (commit 917c606).
  • If downstream systems rely on exact log text or the previously present suggestion/retryConfig fields, adjust those systems; this release intentionally reduces the textual/logging surface area (commit fee93da).
  • No functional API changes to public client methods are included in these commits; the changes are limited to logging shape, error message verbosity, tests, and package metadata.

Relevant commits

  • Remove verbose structured logger implementations and relax logging/error assertions: fee93da
  • Bump several Fjell packages, add @fjell/logging and deepmerge to runtime deps: 917c606
  • Bump package version from dev snapshot to release in package.json (4.4.68): 8a73932

If you maintain tests or automation that depend on exact log messages or on the previous verbose error texts, update them as shown above. Otherwise, no additional action is required for typical usage of the client API.

Assets 2
Loading