@server-driven-impact/tanstack-query 0.5.0-cache-contract.2

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @server-driven-impact/tanstack-query
+
+## 0.4.1
+
+- Add validated, deduplicated TanStack Query invalidation execution.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Woohyun Park
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,31 @@
+# @server-driven-impact/tanstack-query
+
+[English](./README.md) | [한국어](./README.ko.md)
+
+서버 소유 무효화 응답을 검증하고 exact/partial 지시의 합집합을 한 번의 호출로 TanStack Query에 적용합니다.
+
+```ts
+import { applyCacheInvalidations } from '@server-driven-impact/tanstack-query';
+
+await applyCacheInvalidations(queryClient, response.cacheInvalidation, {
+  contract: {id: 'company-api', version: 1}, scope: currentTenant,
+});
+```
+
+캐시를 건드리기 전에 계약과 요청 당시 scope가 현재 값과 같은지 검사합니다. 일치하는 active/inactive query를 모두 invalidate하고 기본 refetch 대상은 `active`입니다. mutation 완료에 active refetch 완료까지 포함하려면 반환 Promise를 기다리십시오. 별도로 보관하면 이미 커밋된 mutation과 후속 refetch 실패를 구분할 수 있습니다.
+
+`@tanstack/query-core`는 peer dependency입니다. `QueryClient`와 캐시 생명주기는 애플리케이션이 소유합니다.
+
+## 실행기의 보장 범위
+
+- 실제 TanStack `matchQuery`로 exact hash/중첩 부분 키를 매칭합니다. scope/계약이 다르면 취소·무효화 전에 거절합니다.
+- `refetchType` 기본값은 `active`, `none`은 stale 표시만 합니다. disabled/static query는 TanStack의 재조회 제외 규칙을 따릅니다.
+- `cancelRefetch`는 TanStack에 전달하지만, 캐시 데이터가 없는 **최초 조회**를 취소한다고 보장하지 않습니다. 기본 동작에서는 수정 전에 시작한 응답을 재사용할 수 있습니다.
+- `cancelInFlight:true`는 일치하는 query를 먼저 `cancelQueries`로 취소합니다. 최초 조회의 뒤늦은 결과도 버리고 active query를 다시 시작할 수 있습니다. 실제 네트워크 요청 중단에는 queryFn의 AbortSignal 사용도 필요합니다. inactive/disabled query를 무조건 다시 시작하지는 않습니다.
+- `throwOnError` 기본값은 `true`이며 refetch 실패 시 반환 Promise가 reject됩니다. 이미 커밋된 업무 작업의 실패를 의미하지 않습니다. `false`면 refetch 오류를 전파하지 않습니다.
+
+비동기 mutation callback 순서, 동시 command 조정, optimistic rollback, 로그인 응답 차단, artifact/persisted cache 정리는 앱 책임입니다. callback을 먼저 await한 뒤 무효화를 적용하고, 업무 성공과 callback/refetch 실패는 별도로 처리하십시오.
+
+요청 당시의 session generation과 QueryClient를 보관하고 응답 및 callback 이후에도 현재 generation인지 검사합니다. 같은 사용자로 재로그인해도 scope 문자열 비교만으로는 구분할 수 없습니다. 로그아웃/로그인 시 기존 client를 폐기·정리하고 이전 응답을 막아야 합니다. 서버 artifact/계약 변경 시 client reset과 persistence/hydration buster도 앱에서 관리합니다.
+
+후속 캐시 오류 때문에 command를 재실행하거나 커밋된 optimistic 상태를 rollback하지 마십시오. [통합 가이드](../../docs/migrations/cache-contract-0.5.md)에 예제가 있습니다. 최초 조회 경합은 실제 QueryObserver로 취소 유무 두 경로를 검증합니다.

package/README.md

@@ -0,0 +1,31 @@
+# @server-driven-impact/tanstack-query
+
+[English](./README.md) | [한국어](./README.ko.md)
+
+Validates a server-owned invalidation response and applies its exact/partial union to TanStack Query in one call.
+
+```ts
+import { applyCacheInvalidations } from '@server-driven-impact/tanstack-query';
+
+await applyCacheInvalidations(queryClient, response.cacheInvalidation, {
+  contract: {id: 'company-api', version: 1}, scope: currentTenant,
+});
+```
+
+The contract and request-time scope must match before the cache is touched. Matching active and inactive queries are invalidated; the default refetch target is `active`. Await the returned promise when mutation completion should include active refetch completion, or retain it separately to distinguish a committed mutation from a later refetch failure.
+
+`@tanstack/query-core` is a peer dependency. The application owns the `QueryClient` and its cache lifecycle.
+
+## Execution boundaries
+
+- Matching uses TanStack's own `matchQuery`, including exact hashing and partial nested keys. Scope/version mismatch rejects before cancellation or invalidation. Payloads are bounded JSON; they contain no executable predicate.
+- `refetchType` defaults to `active`; `none` only marks stale. Disabled/static queries follow TanStack's refetch exclusions. This does not guarantee all views have refreshed.
+- `cancelRefetch` is forwarded to TanStack. It does **not** reliably cancel an initial fetch without cached data. By default that in-flight result may be reused and may have started before the mutation.
+- Opt into `cancelInFlight:true` to call `cancelQueries` for the matching union before invalidating it. This also cancels first fetches, discards their eventual results, and permits active queries to restart. Physical network cancellation additionally requires the query function to consume its AbortSignal. Inactive/disabled reads do not automatically restart.
+- `throwOnError` defaults to `true`: an awaited refetch error rejects this function, **not** the already committed business operation. `throwOnError:false` suppresses refetch errors. Cancellation due to other app activity is not proof of fresh data.
+
+The executor does not schedule mutation callbacks, serialize concurrent commands, manage optimistic rollback, block auth responses, or clear persisted/artifact caches. Await asynchronous application callbacks **before** applying invalidations. Keep command success and callback/refetch errors in separate handling paths.
+
+Capture the request's session generation and QueryClient. After awaiting the response and callbacks, verify that generation is still current. On logout/login—even for the same user ID—retire and clear the old client and reject its responses. Scope equality alone does not detect such a change. Artifact/contract changes require an app-owned client reset and persistence/hydration buster; no automatic cache reset is performed here.
+
+Do not nest cache-refresh failure into a mutation retry/rollback path. A generic integration example and local prerelease instructions are in the [migration guide](../../docs/migrations/cache-contract-0.5.md). Regression tests exercise real QueryObserver first-fetch overlap both with and without cancellation.

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { type Scalar } from '@server-driven-impact/core';
+import { type CacheContractReference, type CacheInvalidationSet } from '@server-driven-impact/cache-contract';
+import { type QueryClient } from '@tanstack/query-core';
+export type RefetchType = 'active' | 'inactive' | 'all' | 'none';
+export type QueryClientLike = Pick<QueryClient, 'invalidateQueries' | 'cancelQueries'>;
+export interface ApplyCacheInvalidationsOptions {
+    contract: CacheContractReference;
+    scope: Scalar;
+    refetchType?: RefetchType;
+    cancelRefetch?: boolean;
+    /** Also cancels first reads that have no cached data. Default: false. */
+    cancelInFlight?: boolean;
+    /** Propagate refetch failures separately from the already committed command. Default: true. */
+    throwOnError?: boolean;
+}
+export declare function validateCacheInvalidationSet(payload: unknown, expected: Pick<ApplyCacheInvalidationsOptions, 'contract' | 'scope'>): asserts payload is CacheInvalidationSet;
+/**
+ * Invalidates the union of all instructions through one TanStack Query call.
+ * Await the returned promise when mutation completion must include active refetches.
+ */
+export declare function applyCacheInvalidations(queryClient: QueryClientLike, payload: unknown, options: ApplyCacheInvalidationsOptions): Promise<void>;

package/dist/index.js

@@ -0,0 +1,58 @@
+// @ts-self-types="./index.d.ts"
+import { byteLength, canonical, isScalar } from '@server-driven-impact/core';
+import { CACHE_LIMITS, isCacheValue } from '@server-driven-impact/cache-contract';
+import { matchQuery } from '@tanstack/query-core';
+function exactMatch(candidate, filter) {
+    try {
+        return canonical(candidate) === canonical(filter);
+    }
+    catch {
+        return false;
+    }
+}
+export function validateCacheInvalidationSet(payload, expected) {
+    if (!payload || typeof payload !== 'object')
+        throw new Error('UNSUPPORTED_CACHE_INVALIDATION_PROTOCOL');
+    const candidate = payload;
+    validatePayload(candidate, expected);
+}
+function validatePayload(payload, expected) {
+    if (!payload || payload.protocolVersion !== 1)
+        throw new Error('UNSUPPORTED_CACHE_INVALIDATION_PROTOCOL');
+    if (typeof payload.contractId !== 'string' || !payload.contractId.length || !Number.isSafeInteger(payload.contractVersion) || payload.contractVersion < 1) {
+        throw new Error('INVALID_CACHE_CONTRACT_REFERENCE');
+    }
+    if (!isScalar(payload.scope) || !isScalar(expected.scope))
+        throw new Error('INVALID_CACHE_SCOPE');
+    if (payload.contractId !== expected.contract.id || payload.contractVersion !== expected.contract.version) {
+        throw new Error('CACHE_CONTRACT_MISMATCH');
+    }
+    if (!exactMatch(payload.scope, expected.scope))
+        throw new Error('CACHE_SCOPE_MISMATCH');
+    if (!Array.isArray(payload.invalidations) || payload.invalidations.length > CACHE_LIMITS.invalidations)
+        throw new Error('INVALID_CACHE_INVALIDATIONS');
+    for (const invalidation of payload.invalidations) {
+        if (!invalidation || !Array.isArray(invalidation.queryKey) || !invalidation.queryKey.length || !isCacheValue(invalidation.queryKey) || typeof invalidation.exact !== 'boolean') {
+            throw new Error('INVALID_CACHE_INVALIDATION');
+        }
+    }
+    if (byteLength(payload) > CACHE_LIMITS.responseBytes)
+        throw new Error('CACHE_INVALIDATION_BYTE_LIMIT');
+}
+/**
+ * Invalidates the union of all instructions through one TanStack Query call.
+ * Await the returned promise when mutation completion must include active refetches.
+ */
+export async function applyCacheInvalidations(queryClient, payload, options) {
+    validateCacheInvalidationSet(payload, options);
+    const unique = structuredClone([...new Map(payload.invalidations.map(value => [`${value.exact}:${canonical(value.queryKey)}`, value])).values()]);
+    if (!unique.length)
+        return;
+    const predicate = query => unique.some(invalidation => matchQuery(invalidation, query));
+    if (options.cancelInFlight)
+        await queryClient.cancelQueries({ predicate });
+    await queryClient.invalidateQueries({
+        predicate,
+        refetchType: options.refetchType ?? 'active',
+    }, { cancelRefetch: options.cancelRefetch, throwOnError: options.throwOnError ?? true });
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@server-driven-impact/tanstack-query",
+  "version": "0.5.0-cache-contract.2",
+  "description": "TanStack Query executor for server-owned SDI invalidation instructions.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "README.ko.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@server-driven-impact/cache-contract": "^0.5.0-cache-contract.2",
+    "@server-driven-impact/core": "^0.5.0-cache-contract.2"
+  },
+  "peerDependencies": {
+    "@tanstack/query-core": "^5.100.14"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/woohyun-park/server-driven-impact.git",
+    "directory": "packages/sdi-tanstack-query"
+  },
+  "homepage": "https://github.com/woohyun-park/server-driven-impact/tree/main/packages/sdi-tanstack-query#readme",
+  "bugs": {
+    "url": "https://github.com/woohyun-park/server-driven-impact/issues"
+  },
+  "keywords": [
+    "cache",
+    "invalidation",
+    "tanstack-query"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/backend/clean-sdi-package.mjs && tsc -p tsconfig.json && node ../../scripts/backend/annotate-sdi-package.mjs",
+    "typecheck": "tsc -p tsconfig.check.json"
+  }
+}