@veams/status-quo-query 0.4.0 → 0.6.0

package/dist/tracking.js

@@ -0,0 +1,226 @@
+/**
+ * Builds the internal registry that connects named dependency values to TanStack query hashes.
+ *
+ * We intentionally keep two indexes:
+ * - byDependencyName: fast forward lookup for invalidation
+ * - byQueryHash: fast reverse lookup for cleanup when TanStack removes a query
+ *
+ * The reverse index is what lets us react to TanStack `removed` events without scanning the
+ * entire registry and without leaking dead query hashes over time.
+ */
+export function createTrackingRegistry() {
+    // Forward index: dependency name -> serialized dependency value -> query hashes.
+    const byDependencyName = new Map();
+    // Reverse index: query hash -> dependency entries originally registered for that query.
+    const byQueryHash = new Map();
+    return {
+        has: (queryHash) => byQueryHash.has(queryHash),
+        match: (dependencies, mode) => matchTrackedQueryHashes(byDependencyName, dependencies, mode),
+        register: (queryHash, dependencies) => {
+            // Re-registration should replace stale mappings instead of accumulating duplicates.
+            if (byQueryHash.has(queryHash)) {
+                unregisterTrackedQueryHash(byDependencyName, byQueryHash, queryHash);
+            }
+            byQueryHash.set(queryHash, dependencies);
+            for (const dependency of dependencies) {
+                // One query can be addressed through several dependency dimensions at once.
+                const valueMap = getOrCreateMap(byDependencyName, dependency.name);
+                const queryHashes = getOrCreateSet(valueMap, dependency.key);
+                queryHashes.add(queryHash);
+            }
+        },
+        unregister: (queryHash) => {
+            unregisterTrackedQueryHash(byDependencyName, byQueryHash, queryHash);
+        },
+    };
+}
+/**
+ * Extracts tracked dependency entries from the final query-key segment.
+ *
+ * The tracked contract is intentionally strict:
+ * - the last query-key segment must be an object
+ * - `deps` must exist on that object
+ * - only `deps` participates in tracking
+ *
+ * Everything else in the key, including `view`, is still part of the TanStack cache key,
+ * but is ignored for invalidation matching.
+ */
+export function extractTrackedDependencies(queryKey) {
+    const finalSegment = queryKey.at(-1);
+    if (!isPlainObject(finalSegment)) {
+        throw new Error('Tracked queries require the final queryKey segment to be an object with a deps property.');
+    }
+    const dependencies = finalSegment.deps;
+    if (!isPlainObject(dependencies)) {
+        throw new Error('Tracked queries require queryKey[queryKey.length - 1].deps to be a plain object.');
+    }
+    return toTrackedDependencyEntries(dependencies, 'Tracked query dependencies');
+}
+/**
+ * Converts a dependency record into normalized registry entries.
+ *
+ * Normalization happens here so the registry only ever works with one internal shape,
+ * regardless of whether the dependencies came from a query key or a mutation resolver.
+ */
+export function toTrackedDependencyEntries(dependencies, contextLabel) {
+    return Object.entries(dependencies).map(([name, value]) => {
+        assertTrackedDependencyValue(name, value, contextLabel);
+        return {
+            key: serializeTrackedDependencyValue(value),
+            name,
+            value,
+        };
+    });
+}
+/**
+ * Default dependency resolver used by the paired helper.
+ *
+ * This is intentionally permissive with partial results. If a mutation variable object only
+ * exposes some dependency keys, we track only those keys and let the chosen match mode decide
+ * how broad the invalidation should be.
+ */
+export function pickTrackedDependencies(dependencyKeys, variables) {
+    if (!isRecordLike(variables)) {
+        throw new Error('Tracked mutations need object-like variables when using dependencyKeys without resolveDependencies.');
+    }
+    const resolved = {};
+    for (const dependencyKey of dependencyKeys) {
+        if (!(dependencyKey in variables)) {
+            continue;
+        }
+        const value = variables[dependencyKey];
+        assertTrackedDependencyValue(dependencyKey, value, 'Tracked mutation dependency resolution');
+        resolved[dependencyKey] = value;
+    }
+    return resolved;
+}
+/**
+ * Resolves live TanStack queries from tracked query hashes.
+ *
+ * The registry may contain hashes that were valid when the invalidation pass started but have
+ * already disappeared from TanStack's cache. Filtering to live queries here keeps invalidation
+ * exact and avoids relying on stale registry state.
+ */
+export function resolveTrackedQueries(queryClient, queryHashes) {
+    const queries = [];
+    for (const queryHash of queryHashes) {
+        const query = queryClient.getQueryCache().get(queryHash);
+        if (query) {
+            queries.push(query);
+        }
+    }
+    return queries;
+}
+function assertTrackedDependencyValue(name, value, contextLabel) {
+    if (value === null ||
+        value === undefined ||
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean') {
+        return;
+    }
+    throw new Error(`${contextLabel} only support primitive dependency values. "${name}" received ${typeof value}.`);
+}
+function getOrCreateMap(map, key) {
+    const existing = map.get(key);
+    if (existing) {
+        return existing;
+    }
+    const created = new Map();
+    map.set(key, created);
+    return created;
+}
+function getOrCreateSet(map, key) {
+    const existing = map.get(key);
+    if (existing) {
+        return existing;
+    }
+    const created = new Set();
+    map.set(key, created);
+    return created;
+}
+function isPlainObject(value) {
+    if (!isRecordLike(value)) {
+        return false;
+    }
+    return (Object.getPrototypeOf(value) === Object.prototype ||
+        Object.getPrototypeOf(value) === null);
+}
+function isRecordLike(value) {
+    return typeof value === 'object' && value !== null;
+}
+function matchTrackedQueryHashes(byDependencyName, dependencies, mode) {
+    // No dependency input means no automatic invalidation target.
+    if (dependencies.length === 0) {
+        return new Set();
+    }
+    if (mode === 'union') {
+        // Union broadens invalidation to any query that matches at least one dependency pair.
+        const matches = new Set();
+        for (const dependency of dependencies) {
+            for (const queryHash of getTrackedQueryHashes(byDependencyName, dependency)) {
+                matches.add(queryHash);
+            }
+        }
+        return matches;
+    }
+    // Intersection narrows invalidation to queries that match every provided dependency pair.
+    let matches;
+    for (const dependency of dependencies) {
+        const queryHashes = getTrackedQueryHashes(byDependencyName, dependency);
+        if (queryHashes.size === 0) {
+            return new Set();
+        }
+        if (!matches) {
+            matches = new Set(queryHashes);
+            continue;
+        }
+        for (const queryHash of [...matches]) {
+            if (!queryHashes.has(queryHash)) {
+                matches.delete(queryHash);
+            }
+        }
+    }
+    return matches ?? new Set();
+}
+function getTrackedQueryHashes(byDependencyName, dependency) {
+    return byDependencyName.get(dependency.name)?.get(dependency.key) ?? new Set();
+}
+function serializeTrackedDependencyValue(value) {
+    // The registry stores values as strings, so include the primitive type to avoid collisions
+    // such as `"1"` and `1` landing in the same bucket.
+    if (value === null) {
+        return 'null';
+    }
+    if (value === undefined) {
+        return 'undefined';
+    }
+    return `${typeof value}:${String(value)}`;
+}
+function unregisterTrackedQueryHash(byDependencyName, byQueryHash, queryHash) {
+    // If the query hash was never tracked or was already cleaned up, there is nothing to do.
+    const dependencies = byQueryHash.get(queryHash);
+    if (!dependencies) {
+        return;
+    }
+    for (const dependency of dependencies) {
+        const valueMap = byDependencyName.get(dependency.name);
+        if (!valueMap) {
+            continue;
+        }
+        const queryHashes = valueMap.get(dependency.key);
+        if (!queryHashes) {
+            continue;
+        }
+        queryHashes.delete(queryHash);
+        // Prune empty buckets so the registry footprint follows the live TanStack cache.
+        if (queryHashes.size === 0) {
+            valueMap.delete(dependency.key);
+        }
+        if (valueMap.size === 0) {
+            byDependencyName.delete(dependency.name);
+        }
+    }
+    byQueryHash.delete(queryHash);
+}
+//# sourceMappingURL=tracking.js.map

package/dist/tracking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking.js","sourceRoot":"","sources":["../src/tracking.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veams/status-quo-query",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "TanStack Query service layer for the VEAMS StatusQuo ecosystem.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -80,5 +80,19 @@
   },
   "bugs": {
     "url": "https://github.com/Veams/veams/issues"
+  },
+  "release-it": {
+    "git": {
+      "tagName": "${npm.name}@${version}",
+      "pushRepo": "origin",
+      "commitMessage": "chore(status-quo-query): release ${npm.name}@${version}"
+    },
+    "github": {
+      "release": true,
+      "releaseName": "${npm.name}@${version}"
+    },
+    "npm": {
+      "publish": true
+    }
   }
 }

package/src/__tests__/mutation.spec.ts

@@ -40,10 +40,10 @@ describe('Mutation Service', () => {
   it('tracks failed mutations', async () => {
     const queryClient = new QueryClient({ defaultOptions: { mutations: { retry: 0 } } });
     const createMutation = setupMutation(queryClient);
-    const mutationFn = jest.fn().mockRejectedValue(new Error('boom'));
+    const mutationFn = jest.fn((_variables: void) => Promise.reject(new Error('boom')));
     const service = createMutation(mutationFn);
 
-    await expect(service.mutate()).rejects.toThrow('boom');
+    await expect(service.mutate(undefined)).rejects.toThrow('boom');
     expect(service.getSnapshot().status).toBe('error');
   });
 });

package/src/__tests__/tracked.spec.ts

@@ -0,0 +1,276 @@
+import { QueryClient } from '@tanstack/query-core';
+
+import { setupQueryManager } from '../provider';
+
+describe('Tracked Query Invalidation', () => {
+  it('registers tracked queries from deps and ignores view data during invalidation', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const [createQuery, createMutation] = manager.createQueryAndMutation([
+      'applicationId',
+      'productId',
+    ] as const);
+
+    createQuery(
+      [
+        'product',
+        {
+          deps: { applicationId: 'app-1', productId: 'product-1' },
+          view: { page: 2, sort: 'name' },
+        },
+      ],
+      jest.fn().mockResolvedValue('product'),
+      { enabled: false }
+    );
+
+    const mutation = createMutation(jest.fn().mockResolvedValue({ ok: true as const }));
+
+    await mutation.mutate({
+      applicationId: 'app-1',
+      productId: 'product-1',
+      productName: 'Renamed',
+    });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith({
+      exact: true,
+      queryKey: [
+        'product',
+        {
+          deps: { applicationId: 'app-1', productId: 'product-1' },
+          view: { page: 2, sort: 'name' },
+        },
+      ],
+    });
+  });
+
+  it('rejects tracked query keys without a deps object', () => {
+    const manager = setupQueryManager(new QueryClient());
+
+    expect(() =>
+      manager.createQuery(
+        ['invalid', { view: { page: 1 } }] as never,
+        jest.fn().mockResolvedValue('nope')
+      )
+    ).toThrow('Tracked queries require queryKey[queryKey.length - 1].deps to be a plain object.');
+  });
+
+  it('supports partial dependency invalidation by matching only the provided keys', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const [createQuery, createMutation] = manager.createQueryAndMutation([
+      'applicationId',
+      'productId',
+    ] as const);
+
+    createQuery(
+      ['product', { deps: { applicationId: 'app-1', productId: 'product-1' }, view: { page: 1 } }],
+      jest.fn().mockResolvedValue('page-1'),
+      { enabled: false }
+    );
+    createQuery(
+      ['product', { deps: { applicationId: 'app-1', productId: 'product-2' }, view: { page: 2 } }],
+      jest.fn().mockResolvedValue('page-2'),
+      { enabled: false }
+    );
+
+    const mutation = createMutation(jest.fn().mockResolvedValue({ ok: true as const }));
+
+    await mutation.mutate({ applicationId: 'app-1', productName: 'Shared update' });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it('supports union matching and dedupes invalidation calls per query', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const [createQuery, createMutation] = manager.createQueryAndMutation([
+      'applicationId',
+      'productId',
+    ] as const);
+
+    createQuery(
+      ['product', { deps: { applicationId: 'app-1', productId: 'product-1' }, view: { page: 1 } }],
+      jest.fn().mockResolvedValue('product-1'),
+      { enabled: false }
+    );
+    createQuery(
+      ['product', { deps: { applicationId: 'app-1', productId: 'product-2' }, view: { page: 2 } }],
+      jest.fn().mockResolvedValue('product-2'),
+      { enabled: false }
+    );
+    createQuery(
+      ['product', { deps: { applicationId: 'app-2', productId: 'product-1' }, view: { page: 3 } }],
+      jest.fn().mockResolvedValue('product-3'),
+      { enabled: false }
+    );
+
+    const mutation = createMutation(jest.fn().mockResolvedValue({ ok: true as const }), {
+      matchMode: 'union',
+    });
+
+    await mutation.mutate({ applicationId: 'app-1', productId: 'product-1' });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(3);
+  });
+
+  it('supports custom dependency resolution for nested mutation variables', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+
+    manager.createQuery(
+      ['product', { deps: { applicationId: 'app-1', productId: 'product-1' }, view: { page: 1 } }],
+      jest.fn().mockResolvedValue('product'),
+      { enabled: false }
+    );
+
+    const mutation = manager.createMutation(
+      jest.fn().mockResolvedValue({ ok: true as const }),
+      {
+        resolveDependencies: (variables: {
+          payload: { applicationId: string };
+          product: { id: string };
+        }) => ({
+          applicationId: variables.payload.applicationId,
+          productId: variables.product.id,
+        }),
+      }
+    );
+
+    await mutation.mutate({
+      payload: { applicationId: 'app-1' },
+      product: { id: 'product-1' },
+    });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('supports error and settled invalidation timing', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const [createQuery, createMutation] = manager.createQueryAndMutation([
+      'applicationId',
+    ] as const);
+
+    createQuery(
+      ['product', { deps: { applicationId: 'app-1' }, view: { page: 1 } }],
+      jest.fn().mockResolvedValue('product'),
+      { enabled: false }
+    );
+
+    const invalidateOnError = createMutation(jest.fn().mockRejectedValue(new Error('boom')), {
+      invalidateOn: 'error',
+    });
+    const invalidateOnSettled = createMutation(
+      jest.fn().mockRejectedValue(new Error('boom again')),
+      {
+        invalidateOn: 'settled',
+      }
+    );
+
+    await expect(invalidateOnError.mutate({ applicationId: 'app-1' })).rejects.toThrow('boom');
+    await expect(invalidateOnSettled.mutate({ applicationId: 'app-1' })).rejects.toThrow(
+      'boom again'
+    );
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it('cleans removed query hashes out of dependency buckets', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const cacheGetSpy = jest.spyOn(queryClient.getQueryCache(), 'get');
+    const [createQuery, createMutation] = manager.createQueryAndMutation([
+      'applicationId',
+    ] as const);
+
+    const removedQueryKey = [
+      'product',
+      { deps: { applicationId: 'app-1' }, view: { page: 1 } },
+    ] as const;
+
+    createQuery(removedQueryKey, jest.fn().mockResolvedValue('page-1'), {
+      enabled: false,
+    });
+    queryClient.removeQueries({ exact: true, queryKey: removedQueryKey });
+
+    createQuery(
+      ['product', { deps: { applicationId: 'app-1' }, view: { page: 2 } }],
+      jest.fn().mockResolvedValue('page-2'),
+      { enabled: false }
+    );
+    cacheGetSpy.mockClear();
+
+    const mutation = createMutation(jest.fn().mockResolvedValue({ ok: true as const }));
+
+    await mutation.mutate({ applicationId: 'app-1' });
+
+    expect(cacheGetSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('re-registers tracked queries on refetch after TanStack cache removal', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const [createQuery, createMutation] = manager.createQueryAndMutation([
+      'applicationId',
+    ] as const);
+    const queryKey = ['product', { deps: { applicationId: 'app-1' }, view: { page: 1 } }] as const;
+    const query = createQuery(queryKey, jest.fn().mockResolvedValue('product'), {
+      enabled: false,
+    });
+    const mutation = createMutation(jest.fn().mockResolvedValue({ ok: true as const }));
+
+    queryClient.removeQueries({ exact: true, queryKey });
+
+    await mutation.mutate({ applicationId: 'app-1' });
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(0);
+
+    await query.refetch();
+    await mutation.mutate({ applicationId: 'app-1' });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('re-registers tracked queries on subscribe after TanStack cache removal', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const [createQuery, createMutation] = manager.createQueryAndMutation([
+      'applicationId',
+    ] as const);
+    const queryKey = ['product', { deps: { applicationId: 'app-1' }, view: { page: 1 } }] as const;
+    const query = createQuery(queryKey, jest.fn().mockResolvedValue('product'), {
+      enabled: false,
+    });
+    const mutation = createMutation(jest.fn().mockResolvedValue({ ok: true as const }));
+
+    queryClient.removeQueries({ exact: true, queryKey });
+
+    const unsubscribe = query.subscribe(() => undefined);
+    await mutation.mutate({ applicationId: 'app-1' });
+    unsubscribe();
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/index.ts

@@ -4,3 +4,12 @@ export * from './mutation';
 export * from './query';
 // Re-export all provider-related types and functions for cache management.
 export * from './provider';
+// Re-export tracked dependency types used by the additive tracked facade.
+export type {
+  TrackedDependencyRecord,
+  TrackedDependencyValue,
+  TrackedInvalidateOn,
+  TrackedMatchMode,
+  TrackedQueryKey,
+  TrackedQueryKeySegment,
+} from './tracking';