@svadmin/core 0.35.0 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/core",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "author": "zuohuadong",
   "repository": {
     "type": "git",

package/src/context.svelte.ts

@@ -9,12 +9,12 @@ import type { AccessControlProvider } from './permissions.svelte';
 import type { AuditLogProvider } from './audit';
 import type { AgentProvider, ChatProvider } from './chatProvider.svelte';
 import {
-  appendTenantCacheKey,
   createTenantCacheKey,
-  queryKeyMatchesTenant,
   resolveTenantProviderMeta,
   withProviderMeta,
 } from './provider-bundle';
+import { keys } from './query-keys';
+import type { QueryMatcher } from './query-keys';
 import type {
   DataProviderInput,
   ProviderBundle,
@@ -107,10 +107,11 @@ export interface AdminContextAccessor {
   readonly tenantCacheKey: TenantCacheKey | undefined;
   getDataProvider(name?: string): DataProvider;
   getDataProviderNames(): string[];
+  resolveDataProviderName(resourceName: string, overrideName?: string): string;
   getDataProviderForResource(resourceName: string, overrideName?: string): DataProvider;
+  queryKeys(resourceName?: string, overrideName?: string): ReturnType<typeof keys>;
+  queryKeyMatcher(resourceName?: string, overrideName?: string): Pick<QueryMatcher, 'provider' | 'tenant'>;
   getProviderMeta(resourceName: string | undefined, meta?: Record<string, unknown>): Record<string, unknown> | undefined;
-  withTenantCacheKey(queryKey: readonly unknown[]): readonly unknown[];
-  matchesTenantQuery(queryKey: readonly unknown[]): boolean;
   getResource(nameOrIdentifier: string): ResourceDefinition;
   currentPath(): string;
   formatLink(path: string): string;
@@ -271,22 +272,43 @@ export function captureAdminContext(): AdminContextAccessor {
     getDataProviderNames() {
       return accessor.providers ? Object.keys(accessor.providers) : [];
     },
-    getDataProviderForResource(resourceName, overrideName) {
+    resolveDataProviderName(resourceName, overrideName) {
       if (overrideName) {
         try {
-          return accessor.getDataProvider(overrideName);
+          accessor.getDataProvider(overrideName);
+          return overrideName;
         } catch {
-          // Preserve the historical fallback to the resource/default provider.
+          // Fallback to resource/default provider as before.
         }
       }
+
       try {
         const resource = accessor.getResource(resourceName);
-        const dataProviderName = resource.provider?.dataProviderName ?? resource.meta?.dataProviderName;
-        if (dataProviderName) return accessor.getDataProvider(dataProviderName);
+        const providerName = resource.provider?.dataProviderName ?? resource.meta?.dataProviderName;
+        if (providerName) {
+          accessor.getDataProvider(providerName);
+          return providerName;
+        }
       } catch {
-        // Preserve the historical fallback when a resource is not registered.
+        // Preserve fallback when a resource is not found or malformed.
       }
-      return accessor.getDataProvider();
+
+      return 'default';
+    },
+    getDataProviderForResource(resourceName, overrideName) {
+      return accessor.getDataProvider(accessor.resolveDataProviderName(resourceName, overrideName));
+    },
+    queryKeys(resourceName, overrideName) {
+      return keys({
+        provider: accessor.resolveDataProviderName(resourceName ?? '', overrideName),
+        tenant: accessor.tenantCacheKey?.__svadminTenant,
+      });
+    },
+    queryKeyMatcher(resourceName, overrideName) {
+      return {
+        provider: accessor.resolveDataProviderName(resourceName ?? '', overrideName),
+        tenant: accessor.tenantCacheKey?.__svadminTenant,
+      };
     },
     getProviderMeta(resourceName, meta) {
       const resource = resourceName
@@ -304,12 +326,6 @@ export function captureAdminContext(): AdminContextAccessor {
         ...(tenant ? resolveTenantProviderMeta(tenant, accessor.tenantAdapter) : {}),
       };
     },
-    withTenantCacheKey(queryKey) {
-      return appendTenantCacheKey(queryKey, accessor.tenantCacheKey);
-    },
-    matchesTenantQuery(queryKey) {
-      return queryKeyMatchesTenant(queryKey, accessor.tenantCacheKey);
-    },
     getResource(nameOrIdentifier) {
       const resource = accessor.resources.find(
         (candidate) => candidate.identifier === nameOrIdentifier || candidate.name === nameOrIdentifier,

package/src/form-hooks.svelte.ts

@@ -2,7 +2,7 @@ import { useQueryClient } from '@tanstack/svelte-query';
 import { useParsed } from './useParsed.svelte';
 import { getAdminOptions } from './options.svelte';
 import { captureAdminContext } from './context.svelte';
-import { appendTenantCacheKey, queryKeyMatchesTenant } from './provider-bundle';
+import { queryKeyMatches } from './query-keys';
 import { createQuery, createMutation } from '@tanstack/svelte-query';
 import { notifyWithProvider } from './notification.svelte';
 import type { NotificationParams } from './notification.svelte';
@@ -458,9 +458,9 @@ export function useForm<
   // Always create the query — use `enabled` to conditionally activate.
   // This ensures setAction('edit') at runtime will trigger a fetch.
   const query = createQuery(() => ({
-    queryKey: appendTenantCacheKey([
-      options.dataProviderName, resource, 'one', currentId, queryMeta,
-    ], adminContext.tenantCacheKey),
+    queryKey: adminContext.queryKeys(resource, options.dataProviderName).data.one(resource, currentId ?? '', {
+      meta: queryMeta,
+    }),
     queryFn: async () => {
       const result = await provider.getOne<BaseRecord>({ resource, id: currentId as string, meta: queryMeta });
       return result;
@@ -527,15 +527,13 @@ export function useForm<
     onSuccess: (data: { data: TData }, _vars: unknown, context: unknown) => {
       const ctx = context as { targetResource?: string } | undefined;
       const res = ctx?.targetResource ?? resource;
-      invalidateByScopes(
+      invalidateByScopes({
         queryClient,
-        res,
-        invalidateScopes,
-        ['list', 'many'],
-        undefined,
-        options.dataProviderName,
-        (queryKey) => queryKeyMatchesTenant(queryKey, adminContext.tenantCacheKey),
-      );
+        resource: res,
+        scopes: invalidateScopes,
+        defaults: ['list', 'many'],
+        matcher: adminContext.queryKeyMatcher(res, options.dataProviderName),
+      });
       if (!isManualSubmitIdentityCurrent()) return;
       if (successNotification !== false) sendNotification({ type: 'success', message: typeof successNotification === 'string' ? successNotification : i18n.t('common.createSuccess') });
       const pk = adminContext.getResource(res).primaryKey ?? 'id';
@@ -584,13 +582,17 @@ export function useForm<
       if (mutationMode === 'pessimistic') return { targetId: currentId, targetResource: resource };
       const targetId = currentId;
       const targetResource = resource;
-      const dpN = options.dataProviderName;
-      const dp = (q: { queryKey: readonly unknown[] }) =>
-        queryKeyMatchesTenant(q.queryKey, adminContext.tenantCacheKey) && q.queryKey[0] === dpN;
-      await queryClient.cancelQueries({ predicate: (q) => dp(q) && q.queryKey[1] === resource });
-      const previousQueries = queryClient.getQueriesData({ predicate: (q) => dp(q) && q.queryKey[1] === resource });
+      const matcher = adminContext.queryKeyMatcher(resource, options.dataProviderName);
+      const dataMatch = (queryKey: readonly unknown[], fields: { action?: string; id?: string | number } = {}) => queryKeyMatches(queryKey, {
+        ...matcher,
+        kind: 'data',
+        resource,
+        ...fields,
+      });
+      await queryClient.cancelQueries({ predicate: (q) => dataMatch(q.queryKey) });
+      const previousQueries = queryClient.getQueriesData({ predicate: (q) => dataMatch(q.queryKey) });
       if (optimisticUpdateMap?.list !== false) {
-        queryClient.setQueriesData({ predicate: (q) => dp(q) && q.queryKey[1] === resource && q.queryKey[2] === 'list' }, (old: unknown) => {
+        queryClient.setQueriesData({ predicate: (q) => dataMatch(q.queryKey, { action: 'list' }) }, (old: unknown) => {
           if (!old || typeof old !== 'object' || !('data' in old)) return old;
           const o = old as { data: Record<string, unknown>[] };
           const pk = adminContext.getResource(resource).primaryKey ?? 'id';
@@ -598,7 +600,7 @@ export function useForm<
         });
       }
       if (optimisticUpdateMap?.detail !== false && targetId != null) {
-        queryClient.setQueriesData({ predicate: (q) => dp(q) && q.queryKey[1] === resource && q.queryKey[2] === 'one' && q.queryKey[3] === targetId }, (old: Record<string, unknown> | undefined) => old ? { ...old, data: deepMerge((old as Record<string, unknown>).data || {}, variables) } : old);
+        queryClient.setQueriesData({ predicate: (q) => dataMatch(q.queryKey, { action: 'one', id: targetId }) }, (old: Record<string, unknown> | undefined) => old ? { ...old, data: deepMerge((old as Record<string, unknown>).data || {}, variables) } : old);
       }
       return { previousQueries, targetId, targetResource };
     },
@@ -626,15 +628,14 @@ export function useForm<
       const ctx = context as { targetId?: string | number; targetResource?: string } | undefined;
       const targetId = ctx?.targetId ?? currentId;
       const res = ctx?.targetResource ?? resource;
-      invalidateByScopes(
+      invalidateByScopes({
         queryClient,
-        res,
-        invalidateScopes,
-        ['list', 'many', 'detail'],
-        targetId ?? undefined,
-        options.dataProviderName,
-        (queryKey) => queryKeyMatchesTenant(queryKey, adminContext.tenantCacheKey),
-      );
+        resource: res,
+        scopes: invalidateScopes,
+        defaults: ['list', 'many', 'detail'],
+        id: targetId ?? undefined,
+        matcher: adminContext.queryKeyMatcher(res, options.dataProviderName),
+      });
     },
     onError: (error: unknown, _vars: unknown, context: unknown) => {
       const ctx = context as { previousQueries?: [unknown, unknown][] } | undefined;
@@ -776,15 +777,14 @@ export function useForm<
         await provider.update<TData, TVariables>({ resource: safeResource, id: safeId as string | number, variables: submittedValues, meta: safeMeta });
         if (formDestroyed) return;
         const scopes = autoSaveOpts.invalidates ?? ['resourceAll'];
-        invalidateByScopes(
+        invalidateByScopes({
           queryClient,
-          safeResource,
+          resource: safeResource,
           scopes,
-          ['resourceAll'],
-          safeId ?? undefined,
-          options.dataProviderName,
-          (queryKey) => queryKeyMatchesTenant(queryKey, adminContext.tenantCacheKey),
-        );
+          defaults: ['resourceAll'],
+          id: safeId ?? undefined,
+          matcher: adminContext.queryKeyMatcher(safeResource, options.dataProviderName),
+        });
         if (!isRecordIdentityCurrent(scheduledIdentity)) return;
         autoSaveStatus = 'saved';
         lastAutoSaveData = submittedValues;
@@ -814,9 +814,11 @@ export function useForm<
   if (autoSaveOpts?.invalidateOnUnmount) {
     $effect(() => {
       return () => queryClient.invalidateQueries({
-        predicate: (q) => queryKeyMatchesTenant(q.queryKey, adminContext.tenantCacheKey)
-          && q.queryKey[0] === options.dataProviderName
-          && q.queryKey[1] === resource,
+        predicate: (q) => queryKeyMatches(q.queryKey, {
+          ...adminContext.queryKeyMatcher(resource, options.dataProviderName),
+          kind: 'data',
+          resource,
+        }),
       });
     });
   }

package/src/hook-utils.svelte.ts

@@ -5,7 +5,7 @@ import { useQueryClient } from '@tanstack/svelte-query';
 import type { LiveProvider, LiveEvent, LiveMode } from './live.svelte';
 import { captureAdminContext } from './context.svelte';
 import type { AdminContextAccessor } from './context.svelte';
-import { queryKeyMatchesTenant } from './provider-bundle';
+import { dataQueryMatches } from './query-keys';
 import { notifyWithProvider } from './notification.svelte';
 import type { NotificationProvider } from './types';
 
@@ -108,10 +108,10 @@ export function createLiveSubscription(paramsFn: () => LiveSubscriptionParams):
         callback: (event: LiveEvent) => {
           params.onLiveEvent?.(event);
           if (liveMode === 'auto') {
-            const dpN = params.dataProviderName;
-            const dpMatch = (q: { queryKey: readonly unknown[] }) =>
-              queryKeyMatchesTenant(q.queryKey, adminContext.tenantCacheKey) && q.queryKey[0] === dpN;
-            queryClient.invalidateQueries({ predicate: (q) => dpMatch(q) && q.queryKey[1] === params.resource });
+            const matcher = adminContext.queryKeyMatcher(params.resource, params.dataProviderName);
+            queryClient.invalidateQueries({
+              predicate: (q) => dataQueryMatches(q.queryKey, { ...matcher, resource: params.resource }),
+            });
           }
         },
       });

package/src/hooks.svelte.ts

@@ -17,14 +17,12 @@ export type { InvalidateScope, OvertimeConfig } from './options.svelte';
 export { createOvertimeTracker, createLiveSubscription } from './hook-utils.svelte';
 export type { OvertimeResult, OvertimeOptions, NotificationConfig } from './hook-utils.svelte';
 
-// ─── Missing hooks stubs ───────────────────────────────────────────
-// These hooks were in the original monolithic file. They are re-created
-// here as thin wrappers or stubs until they get their own modular files.
+// ─── Additional core hooks ─────────────────────────────────────────
 
 import { createQuery, createInfiniteQuery, createMutation, useQueryClient } from '@tanstack/svelte-query';
 import { getAdminOptions } from './options.svelte';
 import { captureAdminContext } from './context.svelte';
-import { appendTenantCacheKey, queryKeyMatchesTenant } from './provider-bundle';
+import { queryKeyMatches } from './query-keys';
 import { useParsed } from './useParsed.svelte';
 import { createOvertimeTracker, createLiveSubscription, fireSuccessNotification, fireErrorNotification, checkError } from './hook-utils.svelte';
 import { invalidateByScopes, publishLiveEvent } from './mutation-hooks.svelte';
@@ -59,15 +57,12 @@ export function useInfiniteList<TData extends BaseRecord = BaseRecord, TError =
     const resource = options.resource ?? parsed.resource ?? '';
     const provider = adminContext.getDataProviderForResource(resource, options.dataProviderName);
     return {
-    queryKey: appendTenantCacheKey([
-      options.dataProviderName,
-      resource,
-      'infiniteList',
-      options.pagination?.pageSize,
-      options.sorters,
-      options.filters,
-      options.meta,
-    ], adminContext.tenantCacheKey),
+    queryKey: adminContext.queryKeys(resource, options.dataProviderName).data.infiniteList(resource, {
+      pageSize: options.pagination?.pageSize,
+      sorters: options.sorters,
+      filters: options.filters,
+      meta: options.meta,
+    }),
     queryFn: async ({ pageParam = 1 }) => {
       const result = await provider.getList<TData>({
         resource,
@@ -173,9 +168,12 @@ export function useSelect<TData extends BaseRecord = BaseRecord, TOption = { lab
   const query = createQuery<{ data: TData[]; total: number }>(() => {
     const provider = adminContext.getDataProviderForResource(resource, dataProviderName);
     return {
-    queryKey: appendTenantCacheKey([
-      dataProviderName, resource, 'select', allFilters, sorters, pagination, meta,
-    ], adminContext.tenantCacheKey),
+    queryKey: adminContext.queryKeys(resource, dataProviderName).data.select(resource, {
+      filters: allFilters,
+      sorters,
+      pagination,
+      meta,
+    }),
     queryFn: () => provider.getList<TData>({ resource, sorters, filters: allFilters, pagination: { current: 1, pageSize: effectivePageSize }, meta }),
     enabled: options.queryOptions?.enabled ?? true,
     staleTime: options.queryOptions?.staleTime ?? adminOptions.reactQuery?.staleTime,
@@ -188,9 +186,10 @@ export function useSelect<TData extends BaseRecord = BaseRecord, TOption = { lab
     ? createQuery<{ data: TData[] }>(() => {
         const provider = adminContext.getDataProviderForResource(resource, dataProviderName);
         return {
-          queryKey: appendTenantCacheKey([
-            dataProviderName, resource, 'select-defaults', defaultValueIds,
-          ], adminContext.tenantCacheKey),
+          queryKey: adminContext.queryKeys(resource, dataProviderName).data.selectDefaults(resource, {
+            ids: defaultValueIds,
+            meta,
+          }),
           queryFn: async () => {
             if (provider.getMany) return provider.getMany<TData>({ resource, ids: defaultValueIds, meta });
             const results = await Promise.all(defaultValueIds.map(id => provider.getOne<TData>({ resource, id, meta })));
@@ -287,9 +286,12 @@ export function useCustom<TData = unknown, TError = HttpError>(options: UseCusto
   const query = createQuery<{ data: TData }, TError>(() => {
     const provider = adminContext.getDataProvider(options.dataProviderName);
     return {
-    queryKey: appendTenantCacheKey([
-      options.dataProviderName, 'custom', options.url, options.method, options.config, options.meta,
-    ], adminContext.tenantCacheKey),
+    queryKey: adminContext.queryKeys(undefined, options.dataProviderName).custom.call(
+      options.url,
+      options.url,
+      options.method,
+      { config: options.config, meta: options.meta },
+    ),
     queryFn: async () => {
       if (!provider.custom) throw new Error('DataProvider does not support custom method');
       return provider.custom<TData>({
@@ -351,15 +353,13 @@ export function useCustomMutation<TData = unknown, TError = HttpError, TVariable
     },
     onSuccess: (data, params) => {
       if (params.resource && params.invalidates !== false) {
-        invalidateByScopes(
+        invalidateByScopes({
           queryClient,
-          params.resource,
-          params.invalidates,
-          ['list', 'many'],
-          undefined,
-          dataProviderName,
-          (queryKey) => queryKeyMatchesTenant(queryKey, adminContext.tenantCacheKey),
-        );
+          resource: params.resource,
+          scopes: params.invalidates,
+          defaults: ['list', 'many'],
+          matcher: adminContext.queryKeyMatcher(params.resource, dataProviderName),
+        });
       }
     },
     onError: (error) => {
@@ -415,15 +415,12 @@ export function useCreateMany<TData extends BaseRecord = BaseRecord, TError = Ht
     },
     onSettled: (_d, _e, params) => {
       const resName = params.resource ?? resource;
-      invalidateByScopes(
+      invalidateByScopes({
         queryClient,
-        resName,
-        undefined,
-        ['list', 'many'],
-        undefined,
-        params.dataProviderName,
-        (queryKey) => queryKeyMatchesTenant(queryKey, adminContext.tenantCacheKey),
-      );
+        resource: resName,
+        defaults: ['list', 'many'],
+        matcher: adminContext.queryKeyMatcher(resName, params.dataProviderName),
+      });
     },
   }));
 
@@ -473,22 +470,21 @@ export function useUpdateMany<TData extends BaseRecord = BaseRecord, TError = Ht
     },
     onSettled: (_d, _e, params) => {
       const resName = params.resource ?? resource;
-      invalidateByScopes(
+      invalidateByScopes({
         queryClient,
-        resName,
-        undefined,
-        ['list', 'many', 'detail'],
-        undefined,
-        params.dataProviderName,
-        (queryKey) => queryKeyMatchesTenant(queryKey, adminContext.tenantCacheKey),
-      );
+        resource: resName,
+        defaults: ['list', 'many', 'detail'],
+        matcher: adminContext.queryKeyMatcher(resName, params.dataProviderName),
+      });
       for (const id of params.ids) {
         queryClient.invalidateQueries({
-          predicate: (q) => queryKeyMatchesTenant(q.queryKey, adminContext.tenantCacheKey)
-            && q.queryKey[0] === params.dataProviderName
-            && q.queryKey[1] === resName
-            && q.queryKey[2] === 'one'
-            && q.queryKey[3] === id,
+          predicate: (q) => queryKeyMatches(q.queryKey, {
+            ...adminContext.queryKeyMatcher(resName, params.dataProviderName),
+            kind: 'data',
+            resource: resName,
+            action: 'one',
+            id,
+          }),
         });
       }
     },
@@ -539,22 +535,21 @@ export function useDeleteMany<TData extends BaseRecord = BaseRecord, TError = Ht
     },
     onSettled: (_d, _e, params) => {
       const resName = params.resource ?? resource;
-      invalidateByScopes(
+      invalidateByScopes({
         queryClient,
-        resName,
-        undefined,
-        ['list', 'many'],
-        undefined,
-        params.dataProviderName,
-        (queryKey) => queryKeyMatchesTenant(queryKey, adminContext.tenantCacheKey),
-      );
+        resource: resName,
+        defaults: ['list', 'many'],
+        matcher: adminContext.queryKeyMatcher(resName, params.dataProviderName),
+      });
       for (const id of params.ids) {
         queryClient.removeQueries({
-          predicate: (q) => queryKeyMatchesTenant(q.queryKey, adminContext.tenantCacheKey)
-            && q.queryKey[0] === params.dataProviderName
-            && q.queryKey[1] === resName
-            && q.queryKey[2] === 'one'
-            && q.queryKey[3] === id,
+          predicate: (q) => queryKeyMatches(q.queryKey, {
+            ...adminContext.queryKeyMatcher(resName, params.dataProviderName),
+            kind: 'data',
+            resource: resName,
+            action: 'one',
+            id,
+          }),
         });
       }
     },
@@ -572,23 +567,22 @@ export function useInvalidate() {
     if (params.invalidates === false) return;
     if (params.invalidates === 'all' || !params.resource) {
       queryClient.invalidateQueries({
-        predicate: (q) => queryKeyMatchesTenant(q.queryKey, adminContext.tenantCacheKey)
-          && q.queryKey[0] === params.dataProviderName,
+        predicate: (q) => queryKeyMatches(q.queryKey, {
+          ...adminContext.queryKeyMatcher(undefined, params.dataProviderName),
+          kind: 'data',
+        }),
       });
       return;
     }
-    const scopes = params.invalidates || ['resourceAll'];
     const res = params.resource;
-    const dpMatch = (q: { queryKey: readonly unknown[] }) =>
-      queryKeyMatchesTenant(q.queryKey, adminContext.tenantCacheKey)
-        && q.queryKey[0] === params.dataProviderName;
-    for (const scope of scopes) {
-      if (scope === 'resourceAll') queryClient.invalidateQueries({ predicate: (q) => dpMatch(q) && q.queryKey[1] === res });
-      else if ((scope === 'detail' || scope === 'one') && params.id) queryClient.invalidateQueries({ predicate: (q) => dpMatch(q) && q.queryKey[1] === res && q.queryKey[2] === 'one' && q.queryKey[3] === params.id });
-      else if (scope === 'detail' || scope === 'one') queryClient.invalidateQueries({ predicate: (q) => dpMatch(q) && q.queryKey[1] === res && q.queryKey[2] === 'one' });
-      else if (scope === 'list') queryClient.invalidateQueries({ predicate: (q) => dpMatch(q) && q.queryKey[1] === res && (q.queryKey[2] === 'list' || q.queryKey[2] === 'infiniteList' || q.queryKey[2] === 'select') });
-      else if (scope === 'many') queryClient.invalidateQueries({ predicate: (q) => dpMatch(q) && q.queryKey[1] === res && q.queryKey[2] === 'many' });
-    }
+    invalidateByScopes({
+      queryClient,
+      resource: res,
+      scopes: params.invalidates || ['resourceAll'],
+      defaults: ['resourceAll'],
+      id: params.id,
+      matcher: adminContext.queryKeyMatcher(res, params.dataProviderName),
+    });
   };
 }
 

package/src/index.ts

@@ -13,16 +13,30 @@ export {
 } from './context.svelte';
 export type { DataProviderInput, AdminContextSource, AdminContextValue, AdminContextAccessor } from './context.svelte';
 export {
-  appendTenantCacheKey,
   createProviderBundle,
   createTenantCacheKey,
   defaultTenantAdapter,
   isTenantCacheKey,
-  queryKeyMatchesTenant,
   resolveTenantProviderMeta,
   withProviderMeta,
   withTenantDataProvider,
 } from './provider-bundle';
+export {
+  dataQueryMatches,
+  isQueryKey,
+  keys,
+  parseQueryKey,
+  queryKeyMatches,
+  queryKeys,
+} from './query-keys';
+export type {
+  DataQueryMatcher,
+  QueryDescriptor,
+  QueryKey,
+  QueryKeysBuilder,
+  QueryKeysContext,
+  QueryMatcher,
+} from './query-keys';
 export type {
   ProviderBundle,
   ProviderMetaInput,
@@ -80,7 +94,6 @@ export type { AdminOptions, TextTransformers, OvertimeConfig } from './options.s
 export { checkError } from './hook-utils.svelte';
 export type { NotificationConfig, OvertimeOptions, OvertimeResult, LiveSubscriptionParams } from './hook-utils.svelte';
 
-export * from './query-keys';
 export { HttpError, UndoError } from './types';
 export type {
   DataProvider, AuthProvider, NotificationProvider, MutationMode,

package/src/live.svelte.ts

@@ -2,7 +2,7 @@
 
 import { useQueryClient } from '@tanstack/svelte-query';
 import { captureAdminContext } from './context.svelte';
-import { queryKeyMatchesTenant } from './provider-bundle';
+import { dataQueryMatches } from './query-keys';
 
 // ─── Types ──────────────────────────────────────────────────────
 
@@ -53,10 +53,10 @@ export function useLive(
         callback: (event) => {
           options?.onLiveEvent?.(event);
           if (liveMode === 'auto') {
-            const dpName = options?.dataProviderName;
-            const dpMatch = (q: { queryKey: readonly unknown[] }) =>
-              queryKeyMatchesTenant(q.queryKey, adminContext.tenantCacheKey) && q.queryKey[0] === dpName;
-            queryClient.invalidateQueries({ predicate: (q) => dpMatch(q) && q.queryKey[1] === res });
+            const matcher = adminContext.queryKeyMatcher(res, options?.dataProviderName);
+            queryClient.invalidateQueries({
+              predicate: (q) => dataQueryMatches(q.queryKey, { ...matcher, resource: res }),
+            });
           }
         },
       });

package/src/mutation-hooks.svelte.ts

@@ -1,8 +1,8 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import { createMutation, useQueryClient } from '@tanstack/svelte-query';
 import { getAdminOptions } from './options.svelte';
 import { captureAdminContext } from './context.svelte';
-import { queryKeyMatchesTenant } from './provider-bundle';
+import { dataQueryMatches } from './query-keys';
+import type { QueryMatcher } from './query-keys';
 import type { AdminContextAccessor } from './context.svelte';
 import { useParsed } from './useParsed.svelte';
 import { auditWithProvider } from './audit';
@@ -39,39 +39,45 @@ export function publishLiveEvent(
  *   - update: ['list', 'many', 'detail']
  *   - delete: ['list', 'many']
  */
-export function invalidateByScopes(
-  queryClient: ReturnType<typeof useQueryClient>,
-  resource: string,
-  scopes: string[] | false | undefined,
-  defaults: string[],
-  id?: string | number,
-  dataProviderName?: string,
-  queryMatches: (queryKey: readonly unknown[]) => boolean = () => true,
-): void {
+export interface InvalidateByScopesRequest {
+  queryClient: ReturnType<typeof useQueryClient>;
+  resource: string;
+  scopes?: string[] | false;
+  defaults: string[];
+  id?: string | number;
+  matcher: Pick<QueryMatcher, 'provider' | 'tenant'>;
+}
+
+export function invalidateByScopes(request: InvalidateByScopesRequest): void {
+  const { queryClient, resource, scopes, defaults, id, matcher } = request;
   if (scopes === false) return;
   const effectiveScopes = (scopes && scopes.length > 0) ? scopes : defaults;
-  const dpMatch = dataProviderName === undefined
-    ? (q: { queryKey: readonly unknown[] }) => queryMatches(q.queryKey)
-    : (q: { queryKey: readonly unknown[] }) => queryMatches(q.queryKey) && q.queryKey[0] === dataProviderName;
+  const dataMatch = (queryKey: readonly unknown[], fields: QueryMatcher = {}) => dataQueryMatches(queryKey, {
+    ...matcher,
+    resource,
+    ...fields,
+  });
   for (const scope of effectiveScopes) {
-    if (scope === 'list') queryClient.invalidateQueries({ predicate: (q) => dpMatch(q) && q.queryKey[1] === resource && (q.queryKey[2] === 'list' || q.queryKey[2] === 'infiniteList' || q.queryKey[2] === 'select' || q.queryKey[2] === 'select-defaults') });
-    else if (scope === 'many') queryClient.invalidateQueries({ predicate: (q) => dpMatch(q) && q.queryKey[1] === resource && q.queryKey[2] === 'many' });
-    else if ((scope === 'detail' || scope === 'one') && id != null) queryClient.invalidateQueries({ predicate: (q) => dpMatch(q) && q.queryKey[1] === resource && q.queryKey[2] === 'one' && q.queryKey[3] === id });
-    else if (scope === 'detail' || scope === 'one') queryClient.invalidateQueries({ predicate: (q) => dpMatch(q) && q.queryKey[1] === resource && q.queryKey[2] === 'one' });
-    else if (scope === 'resourceAll') queryClient.invalidateQueries({ predicate: (q) => dpMatch(q) && q.queryKey[1] === resource });
+    if (scope === 'list') queryClient.invalidateQueries({ predicate: (q) => ['list', 'infiniteList', 'select', 'selectDefaults'].some((action) => dataMatch(q.queryKey, { action })) });
+    else if (scope === 'many') queryClient.invalidateQueries({ predicate: (q) => dataMatch(q.queryKey, { action: 'many' }) });
+    else if ((scope === 'detail' || scope === 'one') && id != null) queryClient.invalidateQueries({ predicate: (q) => dataMatch(q.queryKey, { action: 'one', id }) });
+    else if (scope === 'detail' || scope === 'one') queryClient.invalidateQueries({ predicate: (q) => dataMatch(q.queryKey, { action: 'one' }) });
+    else if (scope === 'resourceAll') queryClient.invalidateQueries({ predicate: (q) => dataMatch(q.queryKey) });
   }
 }
 
-export function deepMerge(target: any, source: any): any {
+export function deepMerge(target: unknown, source: unknown): unknown {
   if (!target || typeof target !== 'object') return source;
   if (!source || typeof source !== 'object') return target;
   if (Array.isArray(source) || source instanceof Date) return source;
-  const result = { ...target };
-  for (const key in source) {
-    if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key]) && !(source[key] instanceof Date)) {
-      result[key] = deepMerge(result[key] || {}, source[key]);
+  const targetRecord = target as Record<string, unknown>;
+  const sourceRecord = source as Record<string, unknown>;
+  const result: Record<string, unknown> = { ...targetRecord };
+  for (const [key, value] of Object.entries(sourceRecord)) {
+    if (value && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)) {
+      result[key] = deepMerge(targetRecord[key] ?? {}, value);
     } else {
-      result[key] = source[key];
+      result[key] = value;
     }
   }
   return result;
@@ -157,15 +163,13 @@ export function useCreate<TData extends BaseRecord = BaseRecord, TError = HttpEr
       );
       publishLiveEvent(resName, 'created', newId != null ? [newId as string | number] : undefined, adminContext);
       // Invalidation in onSuccess for create (refine pattern — no optimistic data to reconcile on error)
-      invalidateByScopes(
+      invalidateByScopes({
         queryClient,
-        resName,
-        params.invalidates,
-        ['list', 'many'],
-        undefined,
-        params.dataProviderName,
-        (queryKey) => queryKeyMatchesTenant(queryKey, adminContext.tenantCacheKey),
-      );
+        resource: resName,
+        scopes: params.invalidates,
+        defaults: ['list', 'many'],
+        matcher: adminContext.queryKeyMatcher(resName, params.dataProviderName),
+      });
       if (typeof options.mutationOptions?.onSuccess === 'function') {
         (options.mutationOptions.onSuccess as (...a: unknown[]) => unknown)(data, params, context);
       }
@@ -263,13 +267,16 @@ export function useUpdate<TData extends BaseRecord = BaseRecord, TError = HttpEr
       if (mutationMode === 'pessimistic') return { _svadmin_ctx: true, userContext };
       const resName = params.resource ?? defaultResource;
       const targetId = params.id ?? defaultId;
-      const dpN = params.dataProviderName;
-      const dp = (q: { queryKey: readonly unknown[] }) =>
-        queryKeyMatchesTenant(q.queryKey, adminContext.tenantCacheKey) && q.queryKey[0] === dpN;
+      const matcher = adminContext.queryKeyMatcher(resName, params.dataProviderName);
+      const dataMatch = (queryKey: readonly unknown[], fields: QueryMatcher = {}) => dataQueryMatches(queryKey, {
+        ...matcher,
+        resource: resName,
+        ...fields,
+      });
       
-      await queryClient.cancelQueries({ predicate: (q) => dp(q) && q.queryKey[1] === resName });
+      await queryClient.cancelQueries({ predicate: (q) => dataMatch(q.queryKey) });
 
-      const previousQueries = queryClient.getQueriesData({ predicate: (q) => dp(q) && q.queryKey[1] === resName });
+      const previousQueries = queryClient.getQueriesData({ predicate: (q) => dataMatch(q.queryKey) });
       
       const pk = adminContext.getResource(resName).primaryKey ?? 'id';
       const updater = params.optimisticUpdateMap ?? { list: true, many: true, detail: true };
@@ -277,14 +284,17 @@ export function useUpdate<TData extends BaseRecord = BaseRecord, TError = HttpEr
       if (updater.detail !== false) {
         const detailFn = updater.detail;
         if (typeof detailFn === 'function') {
-          queryClient.setQueriesData({ predicate: (q) => dp(q) && q.queryKey[1] === resName && q.queryKey[2] === 'one' && q.queryKey[3] === targetId }, (old: unknown) => detailFn(old, params.variables, targetId));
+          queryClient.setQueriesData(
+            { predicate: (q) => dataMatch(q.queryKey, { action: 'one', id: targetId }) },
+            (old: unknown) => detailFn(old, params.variables, targetId),
+          );
         } else {
-          queryClient.setQueriesData({ predicate: (q) => dp(q) && q.queryKey[1] === resName && q.queryKey[2] === 'one' && q.queryKey[3] === targetId }, (old: Record<string, unknown> | undefined) => old ? { ...old, data: deepMerge((old as Record<string, unknown>).data || {}, params.variables) } : old);
+          queryClient.setQueriesData({ predicate: (q) => dataMatch(q.queryKey, { action: 'one', id: targetId }) }, (old: Record<string, unknown> | undefined) => old ? { ...old, data: deepMerge((old as Record<string, unknown>).data || {}, params.variables) } : old);
         }
       }
       
       if (updater.list !== false) {
-        queryClient.setQueriesData({ predicate: (q) => dp(q) && q.queryKey[1] === resName && q.queryKey[2] === 'list' }, (old: unknown) => {
+        queryClient.setQueriesData({ predicate: (q) => dataMatch(q.queryKey, { action: 'list' }) }, (old: unknown) => {
           if (typeof updater.list === 'function') return updater.list(old, params.variables, targetId);
           if (!old || typeof old !== 'object' || !('data' in old)) return old;
           const o = old as { data: Record<string, unknown>[] };
@@ -293,7 +303,7 @@ export function useUpdate<TData extends BaseRecord = BaseRecord, TError = HttpEr
       }
 
       if (updater.many !== false) {
-        queryClient.setQueriesData({ predicate: (q) => dp(q) && q.queryKey[1] === resName && q.queryKey[2] === 'many' }, (old: unknown) => {
+        queryClient.setQueriesData({ predicate: (q) => dataMatch(q.queryKey, { action: 'many' }) }, (old: unknown) => {
           if (typeof updater.many === 'function') return updater.many(old, params.variables, targetId);
           if (!old || typeof old !== 'object' || !('data' in old)) return old;
           const o = old as { data: Record<string, unknown>[] };
@@ -333,15 +343,14 @@ export function useUpdate<TData extends BaseRecord = BaseRecord, TError = HttpEr
       if (error instanceof UndoError) return;
       const resName = params.resource ?? defaultResource;
       const targetId = params.id ?? defaultId;
-      invalidateByScopes(
+      invalidateByScopes({
         queryClient,
-        resName,
-        params.invalidates,
-        ['list', 'many', 'detail'],
-        targetId != null ? targetId : undefined,
-        params.dataProviderName,
-        (queryKey) => queryKeyMatchesTenant(queryKey, adminContext.tenantCacheKey),
-      );
+        resource: resName,
+        scopes: params.invalidates,
+        defaults: ['list', 'many', 'detail'],
+        id: targetId != null ? targetId : undefined,
+        matcher: adminContext.queryKeyMatcher(resName, params.dataProviderName),
+      });
       if (typeof options.mutationOptions?.onSettled === 'function') {
         (options.mutationOptions.onSettled as (...a: unknown[]) => unknown)(_data, error, params, undefined);
       }
@@ -442,26 +451,29 @@ export function useDelete<TData extends BaseRecord = BaseRecord, TError = HttpEr
       if (mutationMode === 'pessimistic') return { _svadmin_ctx: true, userContext };
       const resName = params.resource ?? defaultResource;
       const targetId = params.id ?? defaultId;
-      const dpN = params.dataProviderName;
-      const dp = (q: { queryKey: readonly unknown[] }) =>
-        queryKeyMatchesTenant(q.queryKey, adminContext.tenantCacheKey) && q.queryKey[0] === dpN;
+      const matcher = adminContext.queryKeyMatcher(resName, params.dataProviderName);
+      const dataMatch = (queryKey: readonly unknown[], fields: QueryMatcher = {}) => dataQueryMatches(queryKey, {
+        ...matcher,
+        resource: resName,
+        ...fields,
+      });
       
-      await queryClient.cancelQueries({ predicate: (q) => dp(q) && q.queryKey[1] === resName });
+      await queryClient.cancelQueries({ predicate: (q) => dataMatch(q.queryKey) });
 
-      const previousQueries = queryClient.getQueriesData({ predicate: (q) => dp(q) && q.queryKey[1] === resName });
+      const previousQueries = queryClient.getQueriesData({ predicate: (q) => dataMatch(q.queryKey) });
       
       const pk = adminContext.getResource(resName).primaryKey ?? 'id';
       
-      if (targetId != null) queryClient.removeQueries({ predicate: (q) => dp(q) && q.queryKey[1] === resName && q.queryKey[2] === 'one' && q.queryKey[3] === targetId });
+      if (targetId != null) queryClient.removeQueries({ predicate: (q) => dataMatch(q.queryKey, { action: 'one', id: targetId }) });
 
-      queryClient.setQueriesData({ predicate: (q) => dp(q) && q.queryKey[1] === resName && q.queryKey[2] === 'list' }, (old: unknown) => {
+      queryClient.setQueriesData({ predicate: (q) => dataMatch(q.queryKey, { action: 'list' }) }, (old: unknown) => {
         if (!old || typeof old !== 'object' || !('data' in old)) return old;
         const o = old as { data: Record<string, unknown>[]; total?: number };
         const filtered = o.data.filter((item) => String(item[pk]) !== String(targetId));
         return { ...o, data: filtered, total: (o.total ?? o.data.length) - (o.data.length - filtered.length) };
       });
 
-      queryClient.setQueriesData({ predicate: (q) => dp(q) && q.queryKey[1] === resName && q.queryKey[2] === 'many' }, (old: unknown) => {
+      queryClient.setQueriesData({ predicate: (q) => dataMatch(q.queryKey, { action: 'many' }) }, (old: unknown) => {
         if (!old || typeof old !== 'object' || !('data' in old)) return old;
         const o = old as { data: Record<string, unknown>[] };
         return { ...o, data: o.data.filter((item) => String(item[pk]) !== String(targetId)) };
@@ -477,11 +489,12 @@ export function useDelete<TData extends BaseRecord = BaseRecord, TError = HttpEr
       // Remove detail cache entry (refine pattern — no stale show page)
       if (targetId != null) {
         queryClient.removeQueries({
-          predicate: (q) => queryKeyMatchesTenant(q.queryKey, adminContext.tenantCacheKey)
-            && q.queryKey[0] === params.dataProviderName
-            && q.queryKey[1] === resName
-            && q.queryKey[2] === 'one'
-            && q.queryKey[3] === targetId,
+          predicate: (q) => dataQueryMatches(q.queryKey, {
+            ...adminContext.queryKeyMatcher(resName, params.dataProviderName),
+            resource: resName,
+            action: 'one',
+            id: targetId,
+          }),
         });
       }
 
@@ -511,15 +524,14 @@ export function useDelete<TData extends BaseRecord = BaseRecord, TError = HttpEr
       if (error instanceof UndoError) return;
       const resName = params.resource ?? defaultResource;
       const targetId = params.id ?? defaultId;
-      invalidateByScopes(
+      invalidateByScopes({
         queryClient,
-        resName,
-        params.invalidates,
-        ['list', 'many'],
-        targetId != null ? targetId : undefined,
-        params.dataProviderName,
-        (queryKey) => queryKeyMatchesTenant(queryKey, adminContext.tenantCacheKey),
-      );
+        resource: resName,
+        scopes: params.invalidates,
+        defaults: ['list', 'many'],
+        id: targetId != null ? targetId : undefined,
+        matcher: adminContext.queryKeyMatcher(resName, params.dataProviderName),
+      });
       if (typeof options.mutationOptions?.onSettled === 'function') {
         (options.mutationOptions.onSettled as (...a: unknown[]) => unknown)(_data, error, params, undefined);
       }

package/src/provider-bundle.ts

@@ -116,23 +116,6 @@ export function isTenantCacheKey(value: unknown): value is TenantCacheKey {
   );
 }
 
-export function appendTenantCacheKey(
-  queryKey: readonly unknown[],
-  tenantCacheKey: TenantCacheKey | undefined,
-): readonly unknown[] {
-  return tenantCacheKey ? [...queryKey, tenantCacheKey] : queryKey;
-}
-
-export function queryKeyMatchesTenant(
-  queryKey: readonly unknown[],
-  tenantCacheKey: TenantCacheKey | undefined,
-): boolean {
-  const candidate = queryKey.at(-1);
-  const keyTenant = isTenantCacheKey(candidate) ? candidate : undefined;
-  if (!tenantCacheKey) return keyTenant === undefined;
-  return keyTenant?.__svadminTenant === tenantCacheKey.__svadminTenant;
-}
-
 export interface ProviderMetaInput {
   readonly resource?: string;
   readonly meta?: Record<string, unknown>;

package/src/query-hooks.svelte.ts

@@ -1,7 +1,6 @@
 import { createQuery } from '@tanstack/svelte-query';
 import { getAdminOptions } from './options.svelte';
 import { captureAdminContext } from './context.svelte';
-import { appendTenantCacheKey } from './provider-bundle';
 import { useParsed } from './useParsed.svelte';
 import {
   checkError,
@@ -110,9 +109,12 @@ export function useList<TData extends BaseRecord = BaseRecord, TError = HttpErro
     const filters = [...parentFilters, ...(explicitFilters ?? [])];
 
     return {
-      queryKey: appendTenantCacheKey([
-        opts.dataProviderName, resource, 'list', pagination, sorters, filters, meta,
-      ], adminContext.tenantCacheKey),
+      queryKey: adminContext.queryKeys(resource, opts.dataProviderName).data.list(resource, {
+        pagination,
+        sorters,
+        filters,
+        meta,
+      }),
       queryFn: async () => provider.getList<TData>({
         resource,
         pagination,
@@ -210,10 +212,9 @@ export function useOne<TData extends BaseRecord = BaseRecord, TError = HttpError
     const queryOptions = opts.queryOptions;
 
     return {
-      queryKey: appendTenantCacheKey(
-        [opts.dataProviderName, resource, 'one', id, opts.meta],
-        adminContext.tenantCacheKey,
-      ),
+      queryKey: adminContext.queryKeys(resource, opts.dataProviderName).data.one(resource, id ?? '', {
+        meta: cloneQueryKeyPart(opts.meta),
+      }),
       queryFn: async () => {
         if (id == null) throw new Error('useOne requires an id');
         const result = await provider.getOne<TData>({
@@ -330,10 +331,10 @@ export function useMany<TData extends BaseRecord = BaseRecord, TError = HttpErro
     const provider = adminContext.getDataProviderForResource(resource, dataProviderName);
 
     return {
-      queryKey: appendTenantCacheKey(
-        [dataProviderName, resource, 'many', ids, meta],
-        adminContext.tenantCacheKey,
-      ),
+      queryKey: adminContext.queryKeys(resource, dataProviderName).data.many(resource, {
+        ids: cloneQueryKeyPart(ids),
+        meta: cloneQueryKeyPart(meta),
+      }),
       queryFn: async () => {
         if (!ids.length) return { data: [] };
         if (provider.getMany) {

package/src/query-keys.ts

@@ -1,21 +1,127 @@
-export const keys = () => {
-  let _dataProviderName: string | undefined = undefined;
-  let _resource = '';
-  let _action = '';
-  let _params: unknown = undefined;
-
-  const builder = {
-    data: (name: string | undefined) => { _dataProviderName = name; return builder; },
-    resource: (name: string) => { _resource = name; return builder; },
-    action: (name: string) => { _action = name; return builder; },
-    params: (params: unknown) => { _params = params; return builder; },
-    get: (): unknown[] => {
-      const parts: unknown[] = [_dataProviderName, _resource];
-      if (_action) parts.push(_action);
-      if (_params !== undefined) parts.push(_params);
-      return parts;
-    }
+export const NAMESPACE = 'svadmin';
+export const VERSION = 2;
+
+export type QueryKind = 'data' | 'task' | 'access' | 'custom';
+export type QueryDataAction = 'list' | 'infiniteList' | 'one' | 'many' | 'select' | 'selectDefaults';
+export type QueryTaskAction = 'list' | 'one';
+type TenantId = string | number;
+
+type BaseDescriptor = {
+  readonly namespace: typeof NAMESPACE;
+  readonly version: typeof VERSION;
+  readonly provider: string;
+  readonly tenant?: TenantId;
+  readonly resource?: string;
+  readonly id?: string | number;
+  readonly params?: unknown;
+  readonly method?: string;
+};
+
+export type QueryDescriptorData = BaseDescriptor & { readonly kind: 'data'; readonly action: QueryDataAction };
+export type QueryDescriptorTask = BaseDescriptor & { readonly kind: 'task'; readonly action: QueryTaskAction };
+export type QueryDescriptorAccess = BaseDescriptor & { readonly kind: 'access'; readonly action?: 'can' };
+export type QueryDescriptorCustom = BaseDescriptor & { readonly kind: 'custom'; readonly action?: string };
+export type QueryDescriptor = QueryDescriptorData | QueryDescriptorTask | QueryDescriptorAccess | QueryDescriptorCustom;
+export type QueryKey = readonly [descriptor: QueryDescriptor];
+
+export type QueryKeysContext = { readonly provider?: string; readonly tenant?: TenantId; readonly resource?: string; readonly action?: string; readonly id?: string | number; readonly params?: unknown; readonly method?: string };
+export type QueryMatcher = { readonly provider?: string; readonly tenant?: TenantId; readonly resource?: string; readonly action?: string; readonly id?: string | number; readonly method?: string; readonly kind?: QueryKind };
+export type DataQueryMatcher = Omit<QueryMatcher, 'kind'> & { readonly resource: string };
+export type QueryKeysBuilder = {
+  data: { list(resource: string, params?: unknown): QueryKey; infiniteList(resource: string, params?: unknown): QueryKey; one(resource: string, id: string | number, params?: unknown): QueryKey; many(resource: string, params: unknown): QueryKey; select(resource: string, params?: unknown): QueryKey; selectDefaults(resource: string, params?: unknown): QueryKey; };
+  task: { list(params?: unknown): QueryKey; one(id: string | number): QueryKey };
+  access: { can(resource?: string, params?: unknown): QueryKey };
+  custom: { call(resource: string, id: string | number, method?: string, params?: unknown): QueryKey };
+};
+
+function withDefaultProvider(value: string | undefined): string { return value === undefined ? 'default' : value; }
+function assertProvider(provider: string): void { if (!provider.length) throw new Error('provider must be a non-empty string'); }
+
+function makeDescriptor(value: { kind: 'data'; provider?: string; tenant?: TenantId; resource?: string; action: QueryDataAction; id?: string | number; params?: unknown; method?: string; }): QueryDescriptorData;
+function makeDescriptor(value: { kind: 'task'; provider?: string; tenant?: TenantId; resource?: string; action: QueryTaskAction; id?: string | number; params?: unknown; method?: string; }): QueryDescriptorTask;
+function makeDescriptor(value: { kind: 'access'; provider?: string; tenant?: TenantId; resource?: string; action?: 'can'; id?: string | number; params?: unknown; method?: string; }): QueryDescriptorAccess;
+function makeDescriptor(value: { kind: 'custom'; provider?: string; tenant?: TenantId; resource?: string; id?: string | number; action?: string; params?: unknown; method?: string; }): QueryDescriptorCustom;
+function makeDescriptor(value: { kind: QueryKind; provider?: string; tenant?: TenantId; resource?: string; action?: string; id?: string | number; params?: unknown; method?: string; }): QueryDescriptor {
+  const provider = withDefaultProvider(value.provider);
+  assertProvider(provider);
+
+  const base = { namespace: NAMESPACE, version: VERSION, provider, tenant: value.tenant, resource: value.resource, id: value.id, params: value.params, method: value.method } as const;
+  if (value.kind === 'data') return { ...base, kind: 'data', action: value.action } as QueryDescriptorData;
+  if (value.kind === 'task') return { ...base, kind: 'task', action: value.action as QueryTaskAction } as QueryDescriptorTask;
+  if (value.kind === 'access') return { ...base, kind: 'access', action: value.action as 'can' | undefined } as QueryDescriptorAccess;
+  return { ...base, kind: 'custom', action: value.action } as QueryDescriptorCustom;
+}
+
+export function keys(context: QueryKeysContext = {}): QueryKeysBuilder {
+  const base = { provider: withDefaultProvider(context.provider), tenant: context.tenant, resource: context.resource, id: context.id, params: context.params, method: context.method };
+  return {
+    data: {
+      list: (resource, params = base.params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'list', id: base.id, params, method: base.method })],
+      infiniteList: (resource, params = base.params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'infiniteList', id: base.id, params, method: base.method })],
+      one: (resource, id, params = base.params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'one', id, params, method: base.method })],
+      many: (resource, params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'many', params, method: base.method })],
+      select: (resource, params = base.params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'select', id: base.id, params, method: base.method })],
+      selectDefaults: (resource, params = base.params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'selectDefaults', id: base.id, params, method: base.method })],
+    },
+    task: {
+      list: (params = base.params) => [makeDescriptor({ kind: 'task', provider: base.provider, tenant: base.tenant, resource: base.resource, action: 'list', id: base.id, params, method: base.method })],
+      one: (id) => [makeDescriptor({ kind: 'task', provider: base.provider, tenant: base.tenant, resource: base.resource, action: 'one', id, method: base.method })],
+    },
+    access: { can: (resource = base.resource, params = base.params) => [makeDescriptor({ kind: 'access', provider: base.provider, tenant: base.tenant, resource, action: 'can', id: base.id, params, method: base.method })] },
+    custom: { call: (resource, id, method, params) => [makeDescriptor({ kind: 'custom', provider: base.provider, tenant: base.tenant, resource, id, method, params, action: 'call' })] },
   };
+}
 
-  return builder;
+export const queryKeys: QueryKeysBuilder = {
+  data: {
+    list: (resource, params) => keys().data.list(resource, params),
+    infiniteList: (resource, params) => keys().data.infiniteList(resource, params),
+    one: (resource, id, params) => keys().data.one(resource, id, params),
+    many: (resource, params) => keys().data.many(resource, params),
+    select: (resource, params) => keys().data.select(resource, params),
+    selectDefaults: (resource, params) => keys().data.selectDefaults(resource, params),
+  },
+  task: { list: (params) => keys().task.list(params), one: (id) => keys().task.one(id) },
+  access: { can: (resource, params) => keys().access.can(resource, params) },
+  custom: { call: (resource, id, method, params) => keys().custom.call(resource, id, method, params) },
 };
+
+export function parseQueryKey(value: unknown): QueryDescriptor | undefined {
+  if (!Array.isArray(value) || value.length !== 1) return;
+  const candidate = value[0];
+  if (!candidate || typeof candidate !== 'object') return;
+  const descriptor = candidate as QueryDescriptor;
+  if (descriptor.namespace !== NAMESPACE || descriptor.version !== VERSION || typeof descriptor.provider !== 'string' || !descriptor.provider.length) return;
+  if (descriptor.tenant !== undefined && typeof descriptor.tenant !== 'string' && typeof descriptor.tenant !== 'number') return;
+  if (descriptor.resource !== undefined && typeof descriptor.resource !== 'string') return;
+  if (descriptor.id !== undefined && typeof descriptor.id !== 'string' && typeof descriptor.id !== 'number') return;
+  if (descriptor.method !== undefined && typeof descriptor.method !== 'string') return;
+  if (descriptor.kind === 'data' && ['list', 'infiniteList', 'one', 'many', 'select', 'selectDefaults'].includes(descriptor.action)) return descriptor;
+  if (descriptor.kind === 'task' && ['list', 'one'].includes(descriptor.action)) return descriptor;
+  if (descriptor.kind === 'access' && (descriptor.action === undefined || descriptor.action === 'can')) return descriptor;
+  if (descriptor.kind === 'custom' && (descriptor.action === undefined || typeof descriptor.action === 'string')) return descriptor;
+}
+
+export function isQueryKey(value: unknown): value is QueryKey { return parseQueryKey(value) !== undefined; }
+
+function has(value: QueryMatcher, key: keyof QueryMatcher): boolean { return Object.prototype.hasOwnProperty.call(value, key); }
+function matchField(descriptor: QueryDescriptor, matcher: QueryMatcher, key: keyof QueryMatcher): boolean {
+  if (!has(matcher, key)) return true;
+  if (matcher[key] === undefined) return !(key in descriptor) || (descriptor as Record<string, unknown>)[key] === undefined;
+  return (descriptor as Record<string, unknown>)[key] === matcher[key];
+}
+
+export function queryKeyMatches(queryKey: readonly unknown[], matcher: QueryMatcher = {}): boolean {
+  const parsed = parseQueryKey(queryKey);
+  if (!parsed) return false;
+  if (matcher.kind !== undefined && matcher.kind !== parsed.kind) return false;
+  if (has(matcher, 'provider')) {
+    if (matcher.provider === undefined) return parsed.provider === 'default';
+    if (matcher.provider !== parsed.provider) return false;
+  }
+  return matchField(parsed, matcher, 'tenant') && matchField(parsed, matcher, 'resource') && matchField(parsed, matcher, 'action') && matchField(parsed, matcher, 'id') && matchField(parsed, matcher, 'method');
+}
+
+export function dataQueryMatches(queryKey: readonly unknown[], matcher: DataQueryMatcher): boolean {
+  return queryKeyMatches(queryKey, { ...matcher, kind: 'data' });
+}

package/src/task-hooks.svelte.ts

@@ -3,10 +3,9 @@ import { getAdminOptions } from './options.svelte';
 import { captureAdminContext } from './context.svelte';
 import type { AdminContextAccessor } from './context.svelte';
 import {
-  appendTenantCacheKey,
-  queryKeyMatchesTenant,
   resolveTenantProviderMeta,
 } from './provider-bundle';
+import { queryKeyMatches } from './query-keys';
 import { checkError, createOvertimeTracker, fireErrorNotification, fireSuccessNotification } from './hook-utils.svelte';
 import type { NotificationConfig, OvertimeOptions } from './hook-utils.svelte';
 import { useTranslation } from './i18n.svelte';
@@ -80,8 +79,11 @@ export function useSubmitTask<
         provider: adminContext.notificationProvider,
       });
       void queryClient.invalidateQueries({
-        predicate: (query) => query.queryKey[0] === 'taskList'
-          && queryKeyMatchesTenant(query.queryKey, adminContext.tenantCacheKey),
+        predicate: (query) => queryKeyMatches(query.queryKey, {
+          ...adminContext.queryKeyMatcher(),
+          kind: 'task',
+          action: 'list',
+        }),
       });
       options.mutationOptions?.onSuccess?.(data, params, context);
     },
@@ -128,7 +130,7 @@ export function useTask<TTask extends TaskRecord = TaskRecord, TError = HttpErro
     const provider = normalizeTaskProvider<TTask>(options.taskProvider, adminContext);
     const queryOptions = options.queryOptions;
     return {
-      queryKey: appendTenantCacheKey(['task', options.taskId], adminContext.tenantCacheKey),
+      queryKey: adminContext.queryKeys().task.one(options.taskId ?? ''),
       queryFn: async () => {
         if (!options.taskId) throw new Error('useTask requires a taskId');
         return provider.get(options.taskId);
@@ -207,10 +209,10 @@ export function useTaskList<TTask extends TaskRecord = TaskRecord, TError = Http
     const provider = normalizeTaskProvider<TTask>(options.taskProvider, adminContext);
     const queryOptions = options.queryOptions;
     return {
-      queryKey: appendTenantCacheKey(
-        ['taskList', options.dlq ? 'dlq' : 'default', options.params],
-        adminContext.tenantCacheKey,
-      ),
+      queryKey: adminContext.queryKeys().task.list({
+        list: options.dlq ? 'dlq' : 'default',
+        params: options.params,
+      }),
       queryFn: async () => {
         if (options.dlq) {
           if (!provider.listDlq) throw new Error('TaskProvider does not implement listDlq');

package/src/useCan.ts

@@ -2,7 +2,6 @@
 
 import { createQuery } from '@tanstack/svelte-query';
 import { captureAdminContext } from './context.svelte';
-import { appendTenantCacheKey } from './provider-bundle';
 import type { Action, CanResult } from './permissions.svelte';
 
 export interface UseCanOptions {
@@ -38,9 +37,11 @@ export function useCan(options: () => UseCanOptions): UseCanResult {
     const opts = options();
     const provider = adminContext.accessControlProvider;
     return {
-      queryKey: appendTenantCacheKey([
-        'useCan', opts.resource, opts.action, opts.params, opts.meta,
-      ], adminContext.tenantCacheKey),
+      queryKey: adminContext.queryKeys(opts.resource).access.can(opts.resource, {
+        action: opts.action,
+        params: opts.params,
+        meta: opts.meta,
+      }),
       queryFn: async () => {
         if (!provider) return { can: true };
         const result = await provider.can({

package/src/utility-hooks.svelte.ts

@@ -2,7 +2,7 @@ import { useForm, type UseFormOptions } from './form-hooks.svelte';
 import { useQueryClient } from '@tanstack/svelte-query';
 import { useParsed } from './useParsed.svelte';
 import { captureAdminContext } from './context.svelte';
-import { queryKeyMatchesTenant } from './provider-bundle';
+import { dataQueryMatches } from './query-keys';
 import { getAdminOptions } from './options.svelte';
 import { t } from './i18n.svelte';
 import type { BaseRecord, HttpError, Filter, KnownResources, ResourceDefinition } from './types';
@@ -59,12 +59,11 @@ export function useModalForm<
     visible = false;
     formState.reset();
     if (options.autoSave?.invalidateOnClose) {
-      const dpN = options.dataProviderName;
-      const dp = (q: { queryKey: readonly unknown[] }) =>
-        queryKeyMatchesTenant(q.queryKey, adminContext.tenantCacheKey) && q.queryKey[0] === dpN;
-      queryClient.invalidateQueries({ predicate: (q) => dp(q) && q.queryKey[1] === formState.resource && (q.queryKey[2] === 'list' || q.queryKey[2] === 'infiniteList' || q.queryKey[2] === 'select') });
-      queryClient.invalidateQueries({ predicate: (q) => dp(q) && q.queryKey[1] === formState.resource && q.queryKey[2] === 'many' });
-      queryClient.invalidateQueries({ predicate: (q) => dp(q) && q.queryKey[1] === formState.resource && q.queryKey[2] === 'one' });
+      const resource = formState.resource;
+      const matcher = adminContext.queryKeyMatcher(resource, options.dataProviderName);
+      queryClient.invalidateQueries({
+        predicate: (q) => dataQueryMatches(q.queryKey, { ...matcher, resource }),
+      });
     }
   }