Skip to content

Location-key ordering validation, path-building hardening, and dependency hygiene v4.4.x

Choose a tag to compare

View all tags
released this 19 Oct 23:10
· 35 commits to working since this release
v4.4.46
a2e5314

This release introduces robust client-side validation for location-key ordering, streamlines path construction, aligns public error handling, and performs comprehensive dependency/lockfile hygiene. It also expands test coverage, adds targeted documentation, and simplifies CI/CD publish workflows. The changes are organized around the Release Focus on correctness, observability, and deterministic builds, with a strong emphasis on fail-fast diagnostics for misordered location keys.

Opening context

  • The release centers on enforcing correct parent-to-child ordering of location keys during path construction, so malformed URLs are caught early with actionable errors. This improves reliability for complex containment queries and multi-level paths. Coupled with this, path-building logic has been simplified to a single, deterministic flow, reducing edge-case branches and making behavior easier to reason about. The public error surface has been streamlined to expose a consistent error pathway for Fjell HTTP errors, while preserving existing runtime semantics for retries and network failures.

New Features

  • Location-key ordering validation (core feature)
    • Introduced runtime validation validateLocationKeyOrder(keys) in Utilities.
    • validateLocationKeyOrder is invoked from the path-building flow (getPath) to fail-fast on misordered keys, ensuring parent-child sequencing respects the pathNames hierarchy.
    • Clear, descriptive errors are emitted when ordering violations are detected, including the expected order and the received order to aid debugging.
    • Documentation scaffolding added: LOCATION_KEY_ORDERING.md and LOCATION_KEY_VALIDATION_UPDATE.md to explain rules, validation behavior, and usage.
  • Public error handling surface alignment
    • Expose FjellHttpError and related helpers from @fjell/http-api on the public API surface via the main index (src/index.ts).
    • Simplify error handling path in src/ops/errorHandling.ts by removing FjellHttpError-specific retry mutation logic and the in-place mutation of FjellHttpError instances. Retains network/timeout-based retry behavior and generic error enrichment.
  • Path-building simplification and determinism
    • Reworked path construction flow into a single clear path-building sequence (getPath/addPath) with reduced branching and duplication.
    • Improved ID extraction consistency for PriKey vs LocKey and eliminated some variable-shadowing scenarios.
    • Preserved essential logger hooks for traceability while removing brittle branches that previously caused confusion.
  • Documentation and tests for ordering
    • LOCATION_KEY_ORDERING.md provides guidance on required ordering, error cases, examples, and debugging tips.
    • LOCATION_KEY_VALIDATION_UPDATE.md documents the runtime validation design, rationale, and impact.
    • Tests: Extended Utilities tests with positive/negative ordering scenarios; added Utilities.ordering.test.ts to cover root-to-leaf path construction, misordering rejection with clear errors, and LocKeyArray/ComKey inputs.
  • Dependency hygiene and lockfile determinism
    • Removed duplicate/invalid @fjell registry entries across package.json and package-lock.json; normalized to a single canonical entry per version.
    • Aligned patch-series versions for core, http-api, logging, and registry to a cohesive 4.4.x stream.
    • Updated lockfile entries (package-lock.json) to reflect new versions, tarball URLs, and integrity hashes; removed stray lines to ensure deterministic installs.
  • CI/CD workflow simplification
    • Remove dedicated build step from the npm-publish workflow; decouple publish-npm from a separate build step to streamline the pipeline and reduce duplication, while keeping checkout/publish steps intact.
  • Tests and scaffolding
    • Expanded tests for ordering validation to ensure coverage for both LocKeyArray and ComKey-based inputs, including edge cases and error messages.
    • Updated tests to align with new path-building contract and validation behavior.
  • Migration and API surface alignment (non-breaking for existing users, but with clearer behavior)
    • Public API remains compatible overall; enhanced fail-fast behavior for location-key ordering and improved diagnostics.
    • Internal utilities and tests updated to reflect the new validation contract and deterministic path-building.

Improvements and Refactoring

  • Utilities and path-building improvements
    • Added validateLocationKeyOrder(keys) in Utilities and wired it into getPath so misordered keys fail fast.
    • Simplified getPath and addPath to a deterministic single-path construction, removing nested reordering branches and redundant conditionals.
    • Cleaned up id extraction logic (PriKey vs LocKey) and reduced variable shadowing.
    • Maintained minimal logging to record the selected pathName and nextBase without verbose branching.
  • Error surface and public API consolidation
    • FjellHttpError-related exports centralized and made conveniently accessible via the public API surface.
    • Error enrichment kept but without mutating FjellHttpError instances directly, simplifying the overall error handling flow.

Bug Fixes

  • Addressed potential URL construction issues by fail-fast validation of location-key ordering, preventing malformed containment URLs from progressing through the system.
  • Resolved several lockfile determinism issues by removing duplicate entries and aligning patch versions across Fjell packages.
  • Fixed minor import-path inconsistencies by aligning Coordinate type usage with the core surface (where applicable) and tidying imports.

Documentation Updates

  • Location Key Ordering docs added: LOCATION_KEY_ORDERING.md and LOCATION_KEY_VALIDATION_UPDATE.md
  • Migration and API guidance notes prepared for teams upgrading in the 4.4.x track (where applicable)

Testing Improvements

  • New tests for location-key ordering behavior (root-to-leaf and containment paths) under Utilities.
  • Expanded integration/unit tests for path construction with LocKeyArray and ComKey inputs.
  • Tests updated to reflect new fail-fast behavior and clearer error messages for ordering violations.

Breaking Changes

  • No public API signatures were removed; however, the location-key ordering validation introduces a fail-fast error path that may surface earlier diagnostics for malformed requests. Ensure you handle descriptive validation errors when composing paths that rely on multi-level containment.

Migration Guidance

  • A new set of docs explains how location keys must be ordered and how the runtime validation behaves. Review LOCATION_KEY_ORDERING.md and LOCATION_KEY_VALIDATION_UPDATE.md to understand the required key ordering and the nature of validation errors.

What to expect in your environment

  • If you previously relied on malformed or partially ordered location keys, you will now receive a descriptive error at the point of path construction rather than encountering downstream URL construction issues.
  • CI pipelines will have a streamlined publish step due to the removed dedicated build step, but the publish process remains deterministic and checkout/publish oriented.

If you’d like a shorter changelog entry or a PR-style summary tailored to a specific workflow (e.g., release notes for a particular project board), I can provide that as well.

Contributors

fjell
Assets 2
Loading