Skip to content

Type-safety, validation, and processing overhaul for get() and key handling v4.x

Choose a tag to compare

View all tags
released this 13 Oct 21:38
· 47 commits to working since this release
v4.4.52
40e9de6

This release introduces a broad, engineering-focused set of changes aimed at hardening key handling, improving developer ergonomics, and expanding the library's processing capabilities. It delivers compile-time and runtime guarantees for get() across primary and composite libraries, adds centralized key validation, and introduces new processing utilities for references and aggregations. The release also includes extensive test coverage and numerous lockfile and package configuration updates to align dependencies and tooling.

Release Focus and impact

  • Strengthen get() key handling with strict compile-time type enforcement and runtime validation for both primary and composite item libraries.
  • Provide clear, actionable error messages when keys are invalid, including detailed guidance on correct usage and examples.
  • Centralize key validation logic in a shared utility, ensuring consistent behavior across all operations that consume keys.
  • Introduce processing utilities (OperationContext, ReferenceBuilder, AggregationBuilder) to support declarative, cache-backed loading of related data and aggregations.
  • Begin migrating key-related and processing concerns away from the public Options surface into dedicated processing modules, enhancing clarity and maintainability.
  • Improve test coverage around key validation, error messaging, and processing flows across lib and lib-firestore.

New Features

  • Key Validation Infrastructure
    • Added new type utilities and a centralized KeyValidator module to provide compile-time and runtime validation for get() keys.
    • New error classes InvalidKeyTypeError and LocationKeyOrderError for precise diagnostics when keys are malformed or ordered incorrectly.
    • New tests (key-type-safety.test.ts) validating PriKey vs ComKey usage, location key order, and error messaging.
  • Processing Subsystem (preview)
    • Added foundational processing components: OperationContext, ReferenceBuilder, AggregationBuilder, and an index that exports processing functionality.
    • Updated Options surface to reference the new processing definitions and to remove direct exposure of references/aggregations arrays from Options.
    • Tests for processing utilities covering serialization, caching, and cycle detection.

Improvements

  • Get() Type Safety (Compile-time)
    • Compile-time safety now enforces: primary libraries use PriKey, composite libraries use ComKey<S, L1, L2, L3, L4, L5> for get().
    • Type utilities ensure the correct shape of keys based on library depth (kta).
  • Get() Runtime Validation (Runtime)
    • At runtime, the library validates key types and structure before performing any operation, returning clear errors if mismatches are detected.
    • For composite libraries, loc arrays must mirror the kta hierarchy; for primary libraries, only PriKey is allowed.
  • Clear Error Messages
    • InvalidKeyTypeError now provides a detailed, actionable message including expected vs received formats and example usage.
    • LocationKeyOrderError provides explicit guidance when the loc ordering does not match the library’s hierarchy.

Bug Fixes and Behavioral Adjustments

  • Consistent validation path across operations that accept keys
    • Validation is performed at the start of each operation wrapper, ensuring misuses fail fast with helpful messages.
  • Removed noisy internal logging from core operation wrappers
    • Logging in several operation wrappers (for example, create/update/remove/etc) has been pared back to reduce noise while preserving behavior and hook semantics.
  • Notable test and test-structure updates
    • Added comprehensive tests for key-type safety and error messaging, plus tests for the new processing components.
    • Adjusted tests to align with the new processing and validation surface, and prepared groundwork for a broader test suite around processing behaviors.

Breaking Changes (Guidance)

  • Public surface adjustments
    • The new processing subsystem moves references/aggregations configuration away from the Options surface and into dedicated processing modules. If you were relying on direct Options exposure for these arrays, you will need to migrate to the new processing APIs.
  • Validation and error paths
    • Incorrect key usage now fails with explicit InvalidKeyTypeError or LocationKeyOrderError rather than producing opaque not-found errors or runtime failures. This is by design to improve diagnosability and reduce debugging time.

Migration Guidance

  • For library users
    • If you previously passed ComKey where PriKey was expected (or vice versa), TypeScript will catch this at compile time for composite vs primary libraries. If bypassed (e.g., any usage), runtime errors will guide you to the correct usage with concrete examples.
    • When using composite libraries, ensure loc arrays align with the kta hierarchy (e.g., for kta = ['comments', 'documents', 'annotations'], loc order must reflect documents before annotations).
  • For library maintainers
    • The centralized validation utilities should simplify future changes to key handling. Update or extend the validator as needed and leverage the new error types to maintain consistent diagnostics.
    • Processing features are introduced as clearly separated modules; adopt these patterns to implement future features around references and aggregations.

Testing and Validation

  • Unit tests and integration-like tests for key-type safety (16+ tests described in the suite) validate compile-time and runtime validation pathways across primary and composite libraries.
  • Tests cover: valid PriKey and ComKey paths, invalid key structures, invalid types, location key order correctness, and error message quality.
  • All tests related to key validation and error messaging are designed to ensure clear guidance lines are present in error output.

Documentation and Examples

  • Added example usage for key-type safety (examples/key-type-safety-example.ts) to illustrate correct usage patterns for both primary and composite libraries.
  • Documentation scaffolding and code comments describe the rationale behind the new InvalidKeyTypeError and LocationKeyOrderError messages and how to interpret them.

Release Size Context

  • This is a LARGE release with numerous changes spanning type-safety, runtime validation, error messaging, new processing scaffolding, and substantial test coverage. It includes multiple new source files, significant refactoring of error handling paths, and lockfile/package.json synchronization across the repository.

Files touched (highlights):

  • lib: Added Type Safety + Key Validation (new KeyTypeUtils.ts, validation/KeyValidator.ts), tests/key-type-safety.test.ts, errors.ts enhancements, get.ts and Operations wiring adjustments, contained/Operations.ts, primary/Operations.ts, and the overall wrapValidation wiring in operation wrappers.
  • lib-firestore: Propagated key-type safety validation to Firestore paths and added tests for integration/validation behavior.
  • processing (new): OperationContext.ts, ReferenceBuilder.ts, AggregationBuilder.ts, processing/index.ts, updated Options.ts to reference new processing setup.
  • tests: key-type-safety.test.ts and various tests touching actions/facets/updates to align with validation.
  • Example: examples/key-type-safety-example.ts
  • package management: multiple rounds of version bumps, lockfile bumps, and cleanup of hard-coded version fields to align with release tooling.

If you’d like, I can tailor these notes to emphasize a particular subset (e.g., compile-time safety vs runtime messaging) or adjust the structure to align precisely with your project's release-note templates.

Assets 2
Loading