@robohall/react-query-factory 1.2.0 → 2.0.0

package/README.md

@@ -1,7 +1,8 @@
 # @robohall/react-query-factory
 
 [![npm](https://img.shields.io/npm/v/@robohall/react-query-factory)](https://www.npmjs.com/package/@robohall/react-query-factory)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/@robohall/react-query-factory)](https://bundlephobia.com/package/@robohall/react-query-factory)
+![minified](https://img.shields.io/badge/minified-%3C_12_kB-blue)
+![gzipped](https://img.shields.io/badge/gzipped-%3C_3_kB-blue)
 [![license](https://img.shields.io/npm/l/@robohall/react-query-factory)](./LICENSE)
 
 A factory function for TanStack Query configs. Instead of calling `useQuery` with ad-hoc options, you define a factory once and call it anywhere — getting consistent cache keys, automatic pagination crawling, and `useInfiniteQuery` support for free. TanStack's API stays fully exposed.
@@ -135,22 +136,41 @@ const findInstance = queryFactory(describeInstances, {
     !instances.some(i => i.InstanceId === opts.instanceId),
 });
 
-// query key: ['ec2:DescribeInstances', 'find', { MaxResults: 20 }, { instanceId: 'i-0abc123def456' }]
+// query key: ['ec2:DescribeInstances', { MaxResults: 20 }, 'find', { instanceId: 'i-0abc123def456' }]
 // crawls pages until the target instance appears, then stops
 const { data } = useQuery(
   findInstance({ MaxResults: 20 }, { instanceId: 'i-0abc123def456' })
 );
 ```
 
-Because `findInstance`'s key is nested under `['ec2:DescribeInstances']`, a single invalidation call busts the parent and all children:
+**Invalidation — broad and scoped:**
+
+Child keys follow the ordering `[...parentNS, params, ...childSegments]`, which means the parent key for a given set of params is always a strict prefix of every child key for those same params:
+
+```
+describeInstances({ MaxResults: 20 })
+  → ['ec2:DescribeInstances', { MaxResults: 20 }]
+
+runningInstances({ MaxResults: 20 })          // select child, no own segments
+  → ['ec2:DescribeInstances', { MaxResults: 20 }]  (same entry — select is not in the key)
+
+findInstance({ MaxResults: 20 }, { instanceId: 'i-abc' })
+  → ['ec2:DescribeInstances', { MaxResults: 20 }, 'find', { instanceId: 'i-abc' }]
+//                              └── params ──────┘ └── own segs ──────────────────┘
+```
+
+This unlocks two invalidation granularities with no extra bookkeeping:
 
 ```typescript
-// after a runInstances/terminateInstances mutation — invalidates everything in the namespace.
-// Calling the factory with no args produces just the namespace key; TanStack prefix-matches it
-// against all entries, so describeInstances, runningInstances, and findInstance are all busted.
+// Broad: zero-arg returns the namespace — busts every variant, every param set
 await queryClient.invalidateQueries(describeInstances());
+
+// Scoped: parent call with params — busts the parent and every child for those params only
+await queryClient.invalidateQueries(describeInstances({ MaxResults: 20 }));
 ```
 
+The scoped form is particularly useful after a targeted mutation: invalidate the one resource that changed without touching unrelated cache entries.
+
 ---
 
 ## Infinite queries
@@ -170,6 +190,8 @@ The `.infinite()` key includes an `'infinite'` segment to keep it separate from
 - `describeInstances({ MaxResults: 20 })` → `['ec2:DescribeInstances', { MaxResults: 20 }]`
 - `describeInstances.infinite({ MaxResults: 20 })` → `['ec2:DescribeInstances', 'infinite', { MaxResults: 20 }]`
 
+Child factories place `params` before their own key segments so that the parent key is always a prefix of the child key for the same params — enabling per-call-site scoped invalidation.
+
 ---
 
 ## Public API

package/dist/index.js

@@ -29,8 +29,7 @@ var FACTORY_CONFIG = /* @__PURE__ */ Symbol("factoryConfig");
 var getEnvelopeNextPageParam = (envelope) => envelope.nextPageParam;
 var noNextPage = () => void 0;
 function resolveKey(namespace, params, crawlOptions) {
-  const base = Array.isArray(namespace) ? namespace : [namespace];
-  const withParams = params === void 0 ? base : [...base, params];
+  const withParams = params === void 0 ? namespace : [...namespace, params];
   if (!crawlOptions) return withParams;
   let defined;
   for (const key in crawlOptions) {
@@ -40,6 +39,19 @@ function resolveKey(namespace, params, crawlOptions) {
   }
   return defined ? [...withParams, defined] : withParams;
 }
+function buildChildKey(parentKey, ownSegments, params, crawlOptions, infinite) {
+  let defined;
+  for (const key in crawlOptions) {
+    if (crawlOptions[key] !== void 0) {
+      (defined != null ? defined : defined = {})[key] = crawlOptions[key];
+    }
+  }
+  if (params === void 0 && !defined) return [...parentKey];
+  const withParams = params !== void 0 ? [...parentKey, params] : [...parentKey];
+  const withOwn = [...withParams, ...ownSegments];
+  const withInfinite = infinite ? [...withOwn, "infinite"] : withOwn;
+  return defined ? [...withInfinite, defined] : withInfinite;
+}
 function wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOptions, select) {
   return (lastPage, allPages, lastPageParam, allPageParams) => {
     const combined = select ? select(lastPage) : lastPage;
@@ -106,6 +118,7 @@ function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNext
 function buildFactory(cfg) {
   const {
     queryKey: namespace,
+    parentKey,
     queryFn: rawQueryFn,
     select,
     getNextPageParam,
@@ -115,6 +128,8 @@ function buildFactory(cfg) {
     reduce,
     standardOptions
   } = cfg;
+  const ownSegments = parentKey !== void 0 ? namespace.slice(parentKey.length) : namespace;
+  const infiniteNamespace = [...namespace, "infinite"];
   const hasCrawling = rawQueryFn !== void 0 && getNextPageParam !== void 0 && shouldFetchNextPage !== void 0;
   const hasInfiniteCrawling = hasCrawling && reduce !== void 0;
   const crawlingFn = hasCrawling ? buildCrawlingQueryFn(
@@ -130,7 +145,6 @@ function buildFactory(cfg) {
     shouldFetchNextPage,
     reduce
   ) : void 0;
-  const infiniteNamespace = [...resolveKey(namespace, void 0), "infinite"];
   const envelopeSelect = infiniteCrawlingFn ? (data) => ({
     ...data,
     pages: data.pages.map((e) => select ? select(e.data) : e.data)
@@ -140,7 +154,7 @@ function buildFactory(cfg) {
     pages: data.pages.map(select)
   }) : void 0;
   const factory = function(params, crawlOptions = {}) {
-    const queryKey = resolveKey(namespace, params, crawlOptions);
+    const queryKey = parentKey !== void 0 ? buildChildKey(parentKey, ownSegments, params, crawlOptions) : resolveKey(namespace, params, crawlOptions);
     const resolvedQueryFn = crawlingFn ? (ctx) => crawlingFn(params, crawlOptions, ctx) : rawQueryFn ? (ctx) => rawQueryFn(params, ctx) : void 0;
     return {
       ...standardOptions,
@@ -151,7 +165,7 @@ function buildFactory(cfg) {
     };
   };
   factory.infinite = function(params, crawlOptions = {}) {
-    const queryKey = resolveKey(infiniteNamespace, params, crawlOptions);
+    const queryKey = parentKey !== void 0 ? buildChildKey(parentKey, ownSegments, params, crawlOptions, true) : resolveKey(infiniteNamespace, params, crawlOptions);
     if (infiniteCrawlingFn) {
       return {
         ...standardOptions,
@@ -236,6 +250,7 @@ function queryFactory(configOrParent, childConfig) {
     } = childConfig;
     return buildFactory({
       queryKey: composedNamespace,
+      parentKey: parentCfg.queryKey,
       queryFn: hasNewQueryFn ? childConfig.queryFn : parentCfg.queryFn,
       select: resolvedSelect,
       ...crawling,

package/dist/index.mjs

@@ -3,8 +3,7 @@ var FACTORY_CONFIG = /* @__PURE__ */ Symbol("factoryConfig");
 var getEnvelopeNextPageParam = (envelope) => envelope.nextPageParam;
 var noNextPage = () => void 0;
 function resolveKey(namespace, params, crawlOptions) {
-  const base = Array.isArray(namespace) ? namespace : [namespace];
-  const withParams = params === void 0 ? base : [...base, params];
+  const withParams = params === void 0 ? namespace : [...namespace, params];
   if (!crawlOptions) return withParams;
   let defined;
   for (const key in crawlOptions) {
@@ -14,6 +13,19 @@ function resolveKey(namespace, params, crawlOptions) {
   }
   return defined ? [...withParams, defined] : withParams;
 }
+function buildChildKey(parentKey, ownSegments, params, crawlOptions, infinite) {
+  let defined;
+  for (const key in crawlOptions) {
+    if (crawlOptions[key] !== void 0) {
+      (defined != null ? defined : defined = {})[key] = crawlOptions[key];
+    }
+  }
+  if (params === void 0 && !defined) return [...parentKey];
+  const withParams = params !== void 0 ? [...parentKey, params] : [...parentKey];
+  const withOwn = [...withParams, ...ownSegments];
+  const withInfinite = infinite ? [...withOwn, "infinite"] : withOwn;
+  return defined ? [...withInfinite, defined] : withInfinite;
+}
 function wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOptions, select) {
   return (lastPage, allPages, lastPageParam, allPageParams) => {
     const combined = select ? select(lastPage) : lastPage;
@@ -80,6 +92,7 @@ function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNext
 function buildFactory(cfg) {
   const {
     queryKey: namespace,
+    parentKey,
     queryFn: rawQueryFn,
     select,
     getNextPageParam,
@@ -89,6 +102,8 @@ function buildFactory(cfg) {
     reduce,
     standardOptions
   } = cfg;
+  const ownSegments = parentKey !== void 0 ? namespace.slice(parentKey.length) : namespace;
+  const infiniteNamespace = [...namespace, "infinite"];
   const hasCrawling = rawQueryFn !== void 0 && getNextPageParam !== void 0 && shouldFetchNextPage !== void 0;
   const hasInfiniteCrawling = hasCrawling && reduce !== void 0;
   const crawlingFn = hasCrawling ? buildCrawlingQueryFn(
@@ -104,7 +119,6 @@ function buildFactory(cfg) {
     shouldFetchNextPage,
     reduce
   ) : void 0;
-  const infiniteNamespace = [...resolveKey(namespace, void 0), "infinite"];
   const envelopeSelect = infiniteCrawlingFn ? (data) => ({
     ...data,
     pages: data.pages.map((e) => select ? select(e.data) : e.data)
@@ -114,7 +128,7 @@ function buildFactory(cfg) {
     pages: data.pages.map(select)
   }) : void 0;
   const factory = function(params, crawlOptions = {}) {
-    const queryKey = resolveKey(namespace, params, crawlOptions);
+    const queryKey = parentKey !== void 0 ? buildChildKey(parentKey, ownSegments, params, crawlOptions) : resolveKey(namespace, params, crawlOptions);
     const resolvedQueryFn = crawlingFn ? (ctx) => crawlingFn(params, crawlOptions, ctx) : rawQueryFn ? (ctx) => rawQueryFn(params, ctx) : void 0;
     return {
       ...standardOptions,
@@ -125,7 +139,7 @@ function buildFactory(cfg) {
     };
   };
   factory.infinite = function(params, crawlOptions = {}) {
-    const queryKey = resolveKey(infiniteNamespace, params, crawlOptions);
+    const queryKey = parentKey !== void 0 ? buildChildKey(parentKey, ownSegments, params, crawlOptions, true) : resolveKey(infiniteNamespace, params, crawlOptions);
     if (infiniteCrawlingFn) {
       return {
         ...standardOptions,
@@ -210,6 +224,7 @@ function queryFactory(configOrParent, childConfig) {
     } = childConfig;
     return buildFactory({
       queryKey: composedNamespace,
+      parentKey: parentCfg.queryKey,
       queryFn: hasNewQueryFn ? childConfig.queryFn : parentCfg.queryFn,
       select: resolvedSelect,
       ...crawling,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robohall/react-query-factory",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "A factory abstraction for TanStack Query (React Query) with composable keys, crawling support, and automatic infinite query generation",
   "author": "Robert Hall",
   "license": "MIT",