Skip to content

Location Key Ordering Validation Enforced in Client API

Choose a tag to compare

View all tags
released this 15 Oct 18:19
· 40 commits to working since this release
v4.4.41
74c1279

This release introduces a new runtime validation that enforces correct parent-to-child ordering of location keys in the client-api. The validation catches misordered location keys before URL construction, provides actionable error messages, and is accompanied by new documentation and expanded tests. The change improves fail-fast behavior and reduces silent path-building errors when working with multi-level entity hierarchies.

Opening context

  • The core feature adds a runtime check that validates that location keys (LocKey) are provided in the correct hierarchical order according to the entity pathNames. If keys are out of order, a descriptive error is thrown and path construction is halted early. This replaces the previous behavior where misordered keys could produce malformed URLs or silent issues that were hard to debug.
  • The validation is implemented in the Utilities module and invoked as part of the path-building flow when constructing keys for ComKey-like scenarios and nested entity access.
  • Documentation and tests have been added to cover correct and incorrect usage, and to explain how the system derives the expected order from pathNames.

New Features

  • Automatic runtime validation for location key order
    • Added validateLocationKeyOrder(keys) in the Utilities module
    • Integrated validation into getPath/getPath-like flows so ordering is checked prior to path construction
    • Validation uses the entity hierarchy defined by pathNames to determine the correct parent-to-child order
    • If out of order, throws a descriptive error including the expected order and the received order
  • Documentation that explains how to correctly order location keys and how the validation behaves
    • LOCATION_KEY_ORDERING.md: Comprehensive guide with examples, debugging tips, and recommended usage patterns
    • LOCATION_KEY_VALIDATION_UPDATE.md: Summary of the runtime validation feature, design rationale, and test coverage
  • Documentation-driven test coverage updates
    • Tests extended to verify correct ordering yields valid paths and incorrect ordering throws helpful errors
    • Includes scenarios for multi-level hierarchies and ComKey-like usage

Improvements

  • Path-building simplifications and stabilization
    • Refactored and simplified path-building logic in Utilities to reduce branching and clarify ordering behavior
    • Ensured a single, predictable matching/fallback strategy for pathName resolution and key extraction
  • Lockfile and dependency hygiene adjustments accompanying release work
    • Numerous patches to package.json and package-lock.json entries related to core Fjell packages and tooling
    • ESLint tooling updates and related config adjustments to support stricter linting in tests and code
    • These changes are scoped to build tooling and dependency management; no behavioral changes in public APIs beyond validation behavior

Bug Fixes

  • Fail-fast behavior for path generation on misordered keys
    • Before: misordered location keys could lead to confusing 404s or malformed paths
    • Now: a clear runtime error is thrown, detailing the expected order and the offending keys
  • Tests pass and coverage for location key ordering validation is added
    • Expanded test suite covers positive and negative scenarios, including ComKey-like usage with multiple levels

Documentation Updates

  • LOCATION_KEY_ORDERING.md
    • Explains the location key ordering rules, how the validation works, and how to correct common mistakes
    • Includes examples for correct and incorrect usage and debugging tips
  • LOCATION_KEY_VALIDATION_UPDATE.md
    • Summarizes the rationale, design, and testing approach for the new runtime validation
    • Documents backward compatibility and how to update projects to adopt the new validation

Tests

  • Extended tests/Utilities.test.ts to cover:
    • Correct ordering yields expected path generation
    • Incorrect ordering throws descriptive errors including the expected pathNames
    • ComKey-like scenarios with multiple location levels enforce ordering across levels
  • Test coverage supports fail-fast guarantees and helps prevent regression

Developer Experience

  • Clear error messages when location keys are out of order, including the exact expected order based on pathNames and the received order
  • Improved maintainability through a simplified path-building flow, reducing complexity and potential future bugs in path resolution
  • Documentation provides actionable guidance for developers integrating with the client-api and for contributors extending path resolution logic

Technical Details and Affected Files

  • Core implementation
    • src/Utilities.ts: added validateLocationKeyOrder(keys) and integrated it into the path-building flow
    • Path-building logic refactor to consolidate branches and unify key handling (PriKey vs LocKey) for clearer behavior
  • Tests
    • tests/Utilities.test.ts: extended to include new ordering validation tests
  • Documentation
    • LOCATION_KEY_ORDERING.md: new file detailing ordering rules, examples, and debugging tips
    • LOCATION_KEY_VALIDATION_UPDATE.md: new file summarizing the runtime validation feature and its rationale
  • Release hygiene (informational for maintainers)
    • package.json and package-lock.json adjustments across Fjell packages to align versions, lockfile integrity, and ESLint tooling updates

Notes on impact

  • Public API compatibility remains, with the primary behavioral change being the addition of a new runtime validation that catches misordered location keys early in the request-building process.
  • Projects relying on correct key ordering should adjust code paths to ensure parent-to-child ordering is preserved when constructing ComKey loc arrays or multiple location keys.
  • If your code previously relied on silent behavior or late validation, you may now see immediate errors at API call time with clear guidance on the correct order.

This release emphasizes correctness and developer feedback when working with complex nested entity hierarchies, improving reliability and debuggability for client-side path construction.

Assets 2
Loading