Skip to content

feat(webapp-graphql-relay): add route query lifetime ownership - #4

Merged
artem-korolev merged 1 commit into
mainfrom
agent/relay-route-query-lifetimes
Aug 11, 2026
Merged

feat(webapp-graphql-relay): add route query lifetime ownership#4
artem-korolev merged 1 commit into
mainfrom
agent/relay-route-query-lifetimes

Conversation

@artem-korolev

Copy link
Copy Markdown
Member

Summary

  • add a router-independent route-query lifetime with mounted React ownership
  • make loadRouteQuery({ lifetime }) the lifetime-first API while preserving the deprecated raw-abortSignal compatibility overload
  • add deterministic TanStack Router/React/Relay lifecycle and Chromium/Vite coverage
  • publish customer migration guidance through the package docs and Docusaurus
  • request a minor release of @omgjs/labkit-webapp-graphql-relay (expected 3.1.0)

Why

A TanStack loader abort can retire loader ownership while React still presents the previous route during Suspense or pending navigation. Passing that signal directly to loadRouteQuery can therefore dispose a Relay preloaded query reference that still has a mounted consumer.

The new lifetime separates loader ownership from mounted ownership and disposes the query only after the final owner releases it. TanStack routing, cache policy, route definitions, and generated operations remain application-owned.

Compatibility and customer impact

The existing LoadRouteQueryOptions<TQuery> raw-signal type and behavior remain available for abort-only work and are deprecated. Mounted-route wrappers can migrate to LoadRouteQueryLifetimeOptions<TQuery>. The lifetime and raw signal inputs are mutually exclusive, with both TypeScript and runtime validation.

The upgrade guide includes npm/pnpm commands, single- and multi-query migration, preload/history/retry rules, Strict Mode and Suspense behavior, and final teardown.

Validation

  • 25 public-package unit/type-contract tests
  • 27 deterministic TanStack Router/React/Relay integration tests
  • Chromium/Vite direct-entry, pending replacement, reload, history, recreation, and teardown test
  • isolated packed npm/pnpm consumer matrix, including strict and negative peer graphs
  • CJS, native/bundled ESM, declarations, Vite, SSR/provider rendering, and Relay-runtime identity checks
  • full Rush build, lint, test, and verify
  • Rush change-file verification against origin/main
  • Docusaurus synchronization, typecheck, and production build
  • git diff --check

Package versions and changelogs are intentionally left to Rush Delivery after merge.

@artem-korolev
artem-korolev marked this pull request as ready for review August 11, 2026 18:47
@artem-korolev
artem-korolev merged commit 213494b into main Aug 11, 2026
1 check passed
@artem-korolev
artem-korolev deleted the agent/relay-route-query-lifetimes branch August 11, 2026 18:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant