Skip to content

Upstream Alignment, Centralized Validation, and Dependency Hygiene

Choose a tag to compare

View all tags
released this 19 Oct 23:37
· 38 commits to working since this release
v4.4.56
75fca06

This release focuses on aligning the operation surface with the upstream Fjell libraries, introducing a centralized location-key validation layer, and consolidating dependency and lockfile hygiene. It makes foundational changes to context handling, validation, and the internal dependency graph to pave the way for safer upgrades and more predictable behavior. There are no user-facing features added in this release; changes are foundational and mostly impact internal plumbing, tests, and tooling.

Opening context

  • The release prioritizes adopting the upstream Fjell surface for context and builders, consolidating on a single, authoritative validation path, and cleaning up lockfile metadata to reduce drift.
  • Centralized location-key validation (LocationKeyValidator) now governs location key ordering across operations, reducing duplication and potential inconsistencies.
  • Dependency hygiene is improved by canonicalizing Fjell packages and ensuring the lockfile reflects a stable baseline suitable for future upgrades.

New and Updated Features

  • Centralized LocationKeyValidator
    • Added src/validation/LocationKeyValidator.ts
    • Exposes validateLocations and routes all location-key validation through a single entry point
    • Integrated into operation entry points: all.ts, create.ts, find.ts, and one.ts
    • Enforces hierarchical location ordering consistently and handles undefined/empty inputs gracefully
  • Upstream Fjell surface adoption for context/builders
    • Removed local implementations of OperationContext, ReferenceBuilder, and AggregationBuilder
    • Ops now import and use context/builders from the upstream @fjell/lib surface
    • Centralized AsyncLocalStorage usage via upstream context management
    • API surface around operations becomes more predictable and easier to maintain

Improvements and Refactors

  • Validation and error semantics aligned with upstream surface
    • NotFound and related error handling updated to reflect upstream messaging and structure
    • Tests updated to rely on upstream validation surfaces and error semantics
  • Lockfile and dependency hygiene
    • Canonical Fjell dependency surface established in package.json
    • Dedupe and consolidate duplicates for @fjell/core, @fjell/lib, @fjell/registry, and related entries
    • Removed stray dev suffixes in Fjell version fields; aligned to release-style versions (4.x)
    • package-lock.json blocks cleaned up to remove duplicate or obsolete Fjell metadata
    • EOF/newline handling normalized across package.json and package-lock.json
  • Tests and documentation scaffolding updated to reflect upstream surface
    • Tests updated to import upstream validation surfaces (e.g., @fjell/core/validation)
    • Mocks and expectations adjusted to match centralized LocationKeyValidator and upstream context
    • Documentation/test scaffolding aligned with the upstream surface integration

Notable Changes by Area

  • Ops and runtime
    • src/ops/all.ts, src/ops/create.ts, src/ops/find.ts, src/ops/one.ts now route through upstream context/builders
    • Location-key validation moved out of per-operation inline logic and into LocationKeyValidator
    • Reduced local duplication in key handling and validation logic
  • Validation
    • New LocationKeyValidator.ts governs validateLocations across the codebase
    • Centralized validation reduces per-operation variance and improves reliability
  • Dependencies and packaging
    • package.json and package-lock.json updated to reflect canonical Fjell surface
    • All Fjell-related entries deduplicated and versioned consistently on the 4.x baseline
    • EOF/newline hygiene standardized across metadata files
  • Testing
    • Tests reflect upstream surface changes and not-found semantics
    • Mocks updated to leverage upstream validation and context surfaces

Breaking Changes and Compatibility Notes

  • Local context/reference builders removed in favor of upstream Fjell implementations
    • If downstream code or custom integrations directly imported local Builders, they will need to switch to the upstream equivalents
  • Location-key validation moved to a centralized path
    • Inline validations in several operation files were removed; ensure tests and any custom tooling rely on the new LocationKeyValidator pathway
  • NotFound semantics adjusted to align with upstream messaging
    • Error formats for missing items or invalid keys may differ from prior local implementations

Migration Guidance

  • Update imports to use upstream context/builders where needed
  • Refactor any direct references to local OperationContext, ReferenceBuilder, or AggregationBuilder
  • Integrate with the new LocationKeyValidator for any location-key related validation logic
  • Run tests to ensure NotFound wording and error shapes match the upstream expectations

Additional Notes

  • This release lays the groundwork for safer upgrades and more deterministic operation behavior by unifying on the upstream Fjell surface, introducing a single validation path, and cleaning up dependency metadata.
  • No user-facing features were added; focus was on stability, maintainability, and future-proofing.
Assets 2
Loading