@kimesh/query 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,794 @@
+import * as _tanstack_vue_query0 from "@tanstack/vue-query";
+import { QueryClient, QueryClient as QueryClient$1, QueryKey, QueryKey as QueryKey$1, UseInfiniteQueryReturnType, UseQueryReturnType, VueQueryPlugin, VueQueryPluginOptions, queryOptions, useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/vue-query";
+import { FetchContext, FetchContext as FetchContext$1, FetchError, FetchResponse, FetchResponse as FetchResponse$1 } from "ofetch";
+import * as vue0 from "vue";
+import { ComputedRef, MaybeRefOrGetter, Plugin, Ref, WatchSource } from "vue";
+import { RouteLocationNormalized, Router } from "vue-router";
+
+//#region src/plugin.d.ts
+/**
+ * Options for KimeshQueryPlugin
+ */
+interface KimeshQueryPluginOptions extends Omit<VueQueryPluginOptions, 'queryClient'> {
+  /** Custom QueryClient instance */
+  queryClient?: QueryClient$1;
+  /** Default stale time in ms (default: 5s) */
+  staleTime?: number;
+  /** Default GC time in ms (default: 5 min) */
+  gcTime?: number;
+  /** Number of retries on error (default: 1) */
+  retry?: number;
+  /** Refetch on window focus (default: false) */
+  refetchOnWindowFocus?: boolean;
+}
+/**
+ * Create a QueryClient with Kimesh-optimized defaults
+ *
+ * Defaults are designed for typical SPA usage:
+ * - Short stale time (5s) for responsive UX
+ * - Longer GC time (5min) to preserve cache during navigation
+ * - Single retry to recover from transient errors
+ * - No refetch on focus to reduce unnecessary requests
+ */
+declare function createKimeshQueryClient(options?: KimeshQueryPluginOptions): QueryClient$1;
+/**
+ * KimeshQueryPlugin - Centralized query plugin with sensible defaults
+ *
+ * @example
+ * ```ts
+ * import { KimeshQueryPlugin } from '@kimesh/query'
+ *
+ * // Basic usage with defaults
+ * app.use(KimeshQueryPlugin)
+ *
+ * // With custom options
+ * app.use(KimeshQueryPlugin, {
+ *   staleTime: 10 * 1000,
+ *   retry: 2,
+ * })
+ *
+ * // With custom QueryClient
+ * app.use(KimeshQueryPlugin, {
+ *   queryClient: myCustomQueryClient,
+ * })
+ * ```
+ */
+declare const KimeshQueryPlugin: Plugin<KimeshQueryPluginOptions | undefined>;
+//#endregion
+//#region src/fetch/types.d.ts
+/**
+ * Configuration options for creating or configuring a fetch instance.
+ * Used both for instance creation and runtime config.
+ */
+interface KmFetchConfig {
+  baseURL?: string;
+  headers?: Record<string, string>;
+  timeout?: number;
+  retry?: number | false;
+  retryDelay?: number;
+  credentials?: RequestCredentials;
+  onRequest?: (context: FetchContext$1) => void | Promise<void>;
+  onRequestError?: (context: FetchContext$1 & {
+    error: Error;
+  }) => void | Promise<void>;
+  onResponse?: (context: FetchContext$1 & {
+    response: FetchResponse$1<unknown>;
+  }) => void | Promise<void>;
+  onResponseError?: (context: FetchContext$1 & {
+    response: FetchResponse$1<unknown>;
+  }) => void | Promise<void>;
+}
+/**
+ * Options for individual fetch requests.
+ */
+interface KmFetchRequestOptions extends KmFetchConfig {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+  query?: Record<string, unknown>;
+  params?: Record<string, unknown>;
+  body?: unknown;
+  responseType?: 'json' | 'text' | 'blob' | 'arrayBuffer' | 'stream';
+}
+/**
+ * A configured fetch instance with chainable creation.
+ */
+interface KmFetchInstance {
+  <T = unknown>(url: string, options?: KmFetchRequestOptions): Promise<T>;
+  raw<T = unknown>(url: string, options?: KmFetchRequestOptions): Promise<FetchResponse$1<T>>;
+  create(defaults: KmFetchConfig): KmFetchInstance;
+}
+type KmFetchCreateOptions = KmFetchConfig;
+type FetchRuntimeConfig = KmFetchConfig;
+//#endregion
+//#region src/fetch/create-fetch.d.ts
+/**
+ * Create a configured fetch instance.
+ *
+ * @example
+ * ```ts
+ * const api = createKmFetch({
+ *   baseURL: 'https://api.example.com',
+ *   timeout: 5000,
+ * })
+ *
+ * const users = await api('/users')
+ * ```
+ */
+declare function createKmFetch(config?: KmFetchConfig): KmFetchInstance;
+//#endregion
+//#region src/fetch/fetch-plugin.d.ts
+interface FetchPluginOptions {
+  config?: KmFetchConfig;
+  key?: string;
+  disableLayerAware?: boolean;
+}
+interface KimeshAppContext {
+  $config: Record<string, unknown>;
+  $layersConfig: Record<string, Record<string, unknown>>;
+  router: {
+    beforeEach: (guard: (to: {
+      matched: Array<{
+        path: string;
+        meta: {
+          __kimeshLayer?: string;
+        };
+      }>;
+    }) => void) => void;
+  };
+  hooks: {
+    hook: (name: string, callback: (ctx: {
+      to: {
+        matched: Array<{
+          path: string;
+          meta: {
+            __kimeshLayer?: string;
+          };
+        }>;
+      };
+    }) => void) => void;
+  };
+  provide: <T>(name: string, value: T) => void;
+}
+/**
+ * Create a Kimesh runtime plugin for $fetch.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { fetchPlugin } from '@kimesh/query'
+ * export default fetchPlugin()
+ * ```
+ *
+ * @example With custom config
+ * ```typescript
+ * import { fetchPlugin } from '@kimesh/query'
+ * export default fetchPlugin({
+ *   config: {
+ *     onRequest: ({ options }) => {
+ *       options.headers = { ...options.headers, 'X-Custom': 'value' }
+ *     },
+ *   },
+ * })
+ * ```
+ */
+declare function fetchPlugin(options?: FetchPluginOptions): (app: KimeshAppContext) => {
+  provide: {
+    [x: string]: KmFetchInstance;
+  };
+};
+/**
+ * Create a named fetch plugin for multi-instance scenarios.
+ *
+ * @example
+ * ```typescript
+ * export const blogFetch = createNamedFetchPlugin('blogFetch', {
+ *   baseURL: 'https://blog-api.example.com',
+ * })
+ * ```
+ */
+declare function createNamedFetchPlugin(name: string, config?: KmFetchConfig): (app: KimeshAppContext) => {
+  provide: {
+    [x: string]: KmFetchInstance;
+  };
+};
+interface LayerFetchPluginOptions {
+  layer: string;
+  onRequest?: (ctx: {
+    request: string;
+    options: Record<string, unknown>;
+  }) => void;
+  onResponse?: (ctx: {
+    request: string;
+    response: {
+      status: number;
+    };
+  }) => void;
+}
+/**
+ * Create a layer-specific fetch interceptor plugin.
+ * Use this in layer plugins to add logging or modify requests for that layer only.
+ *
+ * @example
+ * ```typescript
+ * // blog/src/plugins/01.fetch.ts
+ * import { layerFetchPlugin } from '@kimesh/query'
+ *
+ * export default layerFetchPlugin({
+ *   layer: 'blog',
+ *   onRequest: ({ request }) => console.log(`[Blog] Fetching: ${request}`),
+ * })
+ * ```
+ */
+declare function layerFetchPlugin(options: LayerFetchPluginOptions): () => void;
+//#endregion
+//#region src/fetch/layer-fetch.d.ts
+/**
+ * Initialize the layer-aware fetch system.
+ */
+declare function initLayerFetch(configs: {
+  layers: Record<string, KmFetchConfig>;
+  default: KmFetchConfig;
+}): void;
+declare function setCurrentLayer(layer: string): void;
+declare function getCurrentLayer(): string;
+/**
+ * Get fetch instance for a specific layer.
+ * Falls back to 'app' layer if the requested layer is not found.
+ */
+declare function getLayerFetch(layer?: string): KmFetchInstance;
+declare function isLayerFetchInitialized(): boolean;
+/**
+ * Layer-aware $fetch proxy.
+ *
+ * Automatically routes requests through the current layer's fetch instance.
+ * When navigating to /blog/*, the current layer becomes 'blog' and uses
+ * the blog layer's configuration.
+ *
+ * @example
+ * ```ts
+ * // In a blog route component - uses blog layer's baseURL
+ * const posts = await $fetch('/posts')
+ *
+ * // Force specific layer
+ * const hostData = await getLayerFetch('app')('/data')
+ * ```
+ */
+declare const $fetch: KmFetchInstance;
+//#endregion
+//#region src/fetch/global-fetch.d.ts
+/**
+ * Initialize the global $fetch instance with runtime config.
+ * Called automatically by Kimesh during app initialization.
+ */
+declare function initGlobalFetch(config: {
+  apiBase?: string;
+  fetch?: KmFetchConfig;
+}): KmFetchInstance;
+/**
+ * Get the global fetch instance. Creates a default instance if not initialized.
+ */
+declare function useGlobalFetch(): KmFetchInstance;
+//#endregion
+//#region src/loader.d.ts
+/**
+ * Loader definition for route data prefetching
+ */
+interface LoaderDefinition<TData = unknown> {
+  queryKey: QueryKey$1;
+  queryFn: () => Promise<TData>;
+  staleTime?: number;
+  gcTime?: number;
+}
+/**
+ * Loader function signature for route components
+ */
+type LoaderFn<TData = unknown> = (to: RouteLocationNormalized) => LoaderDefinition<TData> | LoaderDefinition<TData>[] | null;
+/**
+ * Route component with loader support
+ */
+interface LoadableComponent {
+  loader: LoaderFn;
+}
+/**
+ * Execute a loader and prefetch data
+ */
+declare function executeLoader(queryClient: QueryClient$1, loader: LoaderDefinition | LoaderDefinition[]): Promise<void>;
+/**
+ * Type guard to check if a component has a loader function
+ */
+declare function hasLoader(component: unknown): component is LoadableComponent;
+/**
+ * Extract loaders from route matched components
+ */
+declare function extractLoaders(to: RouteLocationNormalized): LoaderDefinition[];
+//#endregion
+//#region src/prefetch.d.ts
+/**
+ * Options for setupQueryPrefetching
+ */
+interface QueryPrefetchOptions {
+  /** Called when prefetching starts */
+  onStart?: (to: RouteLocationNormalized, loaders: LoaderDefinition[]) => void;
+  /** Called when prefetching completes */
+  onComplete?: (to: RouteLocationNormalized, loaders: LoaderDefinition[]) => void;
+  /** Called on prefetch error */
+  onError?: (error: unknown, to: RouteLocationNormalized) => void;
+  /** Skip prefetching for these paths (regex or string) */
+  exclude?: (string | RegExp)[];
+  /** Only prefetch for these paths */
+  include?: (string | RegExp)[];
+}
+/**
+ * Setup query prefetching on route navigation
+ *
+ * @example
+ * ```ts
+ * import { setupQueryPrefetching } from '@kimesh/query'
+ *
+ * const router = createRouter({ ... })
+ * const queryClient = new QueryClient()
+ *
+ * setupQueryPrefetching(router, queryClient, {
+ *   onStart: (to) => console.log('Prefetching', to.path),
+ *   onError: (error) => console.error('Prefetch failed', error),
+ * })
+ * ```
+ *
+ * @returns Function to remove the guard
+ */
+declare function setupQueryPrefetching(router: Router, queryClient: QueryClient$1, options?: QueryPrefetchOptions): () => void;
+/**
+ * Create a prefetch function for manual prefetching (e.g., on hover)
+ *
+ * @example
+ * ```ts
+ * const prefetch = createPrefetcher(queryClient, router)
+ *
+ * // Prefetch on hover
+ * <RouterLink :to="{ name: 'user' }" @mouseenter="prefetch('/user/123')">
+ * ```
+ */
+declare function createPrefetcher(queryClient: QueryClient$1, router: Router): (path: string) => Promise<void>;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Return type for Nuxt-style composables.
+ */
+interface KmAsyncDataResult<T> {
+  /** Fetched data */
+  data: Ref<T | undefined>;
+  /** Loading state */
+  pending: ComputedRef<boolean>;
+  /** Error if any */
+  error: Ref<Error | null>;
+  /** Status string */
+  status: ComputedRef<'idle' | 'pending' | 'success' | 'error'>;
+  /** Refetch data */
+  refresh: () => Promise<void>;
+  /** Alias for refresh */
+  execute: () => Promise<void>;
+  /** Clear cache and reset */
+  clear: () => void;
+}
+/**
+ * Query key factory result type.
+ */
+type QueryKeyFactory<TRoot extends string, TKeys extends Record<string, ((arg: never) => unknown) | null>> = {
+  all: () => readonly [TRoot];
+} & { [K in keyof TKeys]: TKeys[K] extends null ? () => readonly [TRoot, K] : TKeys[K] extends ((arg: infer A) => infer R) ? (arg: A) => readonly [TRoot, K, R] : never };
+//#endregion
+//#region src/composables/useKmFetch.d.ts
+/**
+ * Options for useKmFetch composable.
+ */
+interface UseKmFetchOptions<T> {
+  /** HTTP method */
+  method?: MaybeRefOrGetter<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'>;
+  /** Query parameters */
+  query?: MaybeRefOrGetter<Record<string, unknown>>;
+  /** Alias for query */
+  params?: MaybeRefOrGetter<Record<string, unknown>>;
+  /** Request body (auto-serialized) */
+  body?: MaybeRefOrGetter<unknown>;
+  /** Request headers */
+  headers?: MaybeRefOrGetter<Record<string, string>>;
+  /** Base URL (overrides global config) */
+  baseURL?: MaybeRefOrGetter<string>;
+  /** Timeout in milliseconds */
+  timeout?: MaybeRefOrGetter<number>;
+  /** Called before each request */
+  onRequest?: (context: FetchContext) => void | Promise<void>;
+  /** Called when request fails */
+  onRequestError?: (context: FetchContext & {
+    error: Error;
+  }) => void | Promise<void>;
+  /** Called after each response */
+  onResponse?: (context: FetchContext & {
+    response: FetchResponse<unknown>;
+  }) => void | Promise<void>;
+  /** Called when response has error status */
+  onResponseError?: (context: FetchContext & {
+    response: FetchResponse<unknown>;
+  }) => void | Promise<void>;
+  /** Custom cache key (auto-generated if not provided) */
+  key?: string;
+  /** Execute immediately (default: true) */
+  immediate?: boolean;
+  /** Watch sources for auto-refetch (false to disable) */
+  watch?: WatchSource[] | false;
+  /** Transform response data */
+  transform?: (data: unknown) => T;
+  /** Default value factory */
+  default?: () => T;
+  /** Stale time in ms */
+  staleTime?: number;
+  /** GC time in ms */
+  gcTime?: number;
+  /** Custom $fetch instance (uses global if not provided) */
+  $fetch?: KmFetchInstance;
+}
+/**
+ * Nuxt-style fetch composable built on $fetch and TanStack Query.
+ *
+ * @example
+ * ```ts
+ * // Simple GET
+ * const { data, pending, error } = useKmFetch('/api/users')
+ *
+ * // With query params
+ * const { data } = useKmFetch('/api/users', {
+ *   query: { page: 1, limit: 10 },
+ * })
+ *
+ * // POST with body
+ * const { data } = useKmFetch('/api/users', {
+ *   method: 'POST',
+ *   body: { name: 'John' },
+ * })
+ *
+ * // With interceptors
+ * const { data } = useKmFetch('/api/protected', {
+ *   onRequest({ options }) {
+ *     options.headers.set('Authorization', `Bearer ${token}`)
+ *   },
+ * })
+ *
+ * // Reactive URL
+ * const userId = ref(1)
+ * const { data } = useKmFetch(() => `/api/users/${userId.value}`)
+ * ```
+ */
+declare function useKmFetch<T>(url: MaybeRefOrGetter<string>, options?: UseKmFetchOptions<T>): KmAsyncDataResult<T>;
+/**
+ * Lazy variant - starts fetching immediately (non-blocking pattern).
+ *
+ * Note: Despite the "lazy" name (Nuxt convention), this starts immediately.
+ * Use this when data loading shouldn't block rendering.
+ */
+declare function useLazyKmFetch<T>(url: MaybeRefOrGetter<string>, options?: UseKmFetchOptions<T>): KmAsyncDataResult<T>;
+//#endregion
+//#region src/composables/useKmAsyncData.d.ts
+/**
+ * Context passed to async data handler.
+ */
+interface KmAsyncDataContext {
+  /** Global $fetch instance */
+  $fetch: KmFetchInstance;
+}
+/**
+ * Options for useKmAsyncData composable.
+ */
+interface UseKmAsyncDataOptions<T> {
+  /** Execute immediately (default: true) */
+  immediate?: boolean;
+  /** Watch sources for auto-refetch */
+  watch?: WatchSource[];
+  /** Transform response data */
+  transform?: (data: unknown) => T;
+  /** Default value factory */
+  default?: () => T;
+  /** Stale time in ms */
+  staleTime?: number;
+  /** GC time in ms */
+  gcTime?: number;
+  /** Custom $fetch instance */
+  $fetch?: KmFetchInstance;
+}
+/**
+ * Generic async data composable.
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const { data, pending } = useKmAsyncData('currentUser', async () => {
+ *   return await api.users.getCurrentUser()
+ * })
+ *
+ * // With $fetch from context
+ * const { data } = useKmAsyncData('users', async ({ $fetch }) => {
+ *   return await $fetch('/api/users')
+ * })
+ *
+ * // With transform
+ * const { data } = useKmAsyncData('posts', fetchPosts, {
+ *   transform: (data) => data.items,
+ * })
+ * ```
+ */
+declare function useKmAsyncData<T>(key: string, handler: (ctx: KmAsyncDataContext) => Promise<T>, options?: UseKmAsyncDataOptions<T>): KmAsyncDataResult<T>;
+/**
+ * Lazy variant - starts fetching immediately (non-blocking pattern).
+ *
+ * Note: Despite the "lazy" name (Nuxt convention), this starts immediately.
+ * Use this when data loading shouldn't block rendering.
+ */
+declare function useLazyKmAsyncData<T>(key: string, handler: (ctx: KmAsyncDataContext) => Promise<T>, options?: UseKmAsyncDataOptions<T>): KmAsyncDataResult<T>;
+//#endregion
+//#region src/composables/useKmData.d.ts
+/**
+ * Access cached data by key
+ *
+ * @example
+ * ```ts
+ * const user = useKmData<User>('currentUser')
+ * // Can also update
+ * user.value = { ...user.value, name: 'New Name' }
+ * ```
+ */
+declare function useKmData<T>(key: string): vue0.WritableComputedRef<T | undefined, T | undefined>;
+//#endregion
+//#region src/define-query.d.ts
+/**
+ * Shared query timing options
+ */
+interface QueryTimingOptions {
+  /** Time in ms before data is considered stale */
+  staleTime?: number;
+  /** Time in ms before unused data is garbage collected */
+  gcTime?: number;
+}
+/**
+ * Query options input with Pinia Colada naming
+ */
+interface QueryOptionsInput<TData, TQueryKey extends QueryKey$1 = QueryKey$1> extends QueryTimingOptions {
+  /** Query key (unique identifier for cache) */
+  key: TQueryKey;
+  /** Query function - Pinia Colada style naming */
+  query?: () => Promise<TData>;
+  /** Query function - TanStack style naming (alias for query) */
+  queryFn?: () => Promise<TData>;
+  /** Whether the query is enabled */
+  enabled?: boolean;
+}
+/**
+ * Output type for defineQueryOptions - compatible with both Pinia Colada and TanStack Query
+ */
+interface QueryOptionsOutput<TData, TQueryKey extends QueryKey$1 = QueryKey$1> extends QueryTimingOptions {
+  key: TQueryKey;
+  query: () => Promise<TData>;
+  queryKey: TQueryKey;
+  queryFn: () => Promise<TData>;
+  enabled?: boolean;
+}
+/**
+ * Define static query options (Pinia Colada style)
+ *
+ * @example
+ * ```ts
+ * // Pinia Colada naming (preferred)
+ * export const postsListQuery = defineQueryOptions({
+ *   key: ['posts', 'list'],
+ *   query: () => api.posts.getAll(),
+ *   staleTime: 5 * 60 * 1000,
+ * })
+ *
+ * // TanStack naming (also supported)
+ * export const postsListQuery = defineQueryOptions({
+ *   key: ['posts', 'list'],
+ *   queryFn: () => api.posts.getAll(),
+ * })
+ *
+ * // Usage with useQuery
+ * const { data } = useQuery(postsListQuery)
+ * ```
+ */
+declare function defineQueryOptions<TData, TQueryKey extends QueryKey$1 = QueryKey$1>(options: QueryOptionsInput<TData, TQueryKey>): QueryOptionsOutput<TData, TQueryKey>;
+/**
+ * Create a reusable query composable (Pinia Colada style)
+ *
+ * @example
+ * ```ts
+ * export const useCurrentUser = defineQuery({
+ *   key: ['user', 'current'],
+ *   query: () => api.users.getCurrentUser(),
+ * })
+ *
+ * // State is shared across components!
+ * const { data: user } = useCurrentUser()
+ * ```
+ */
+declare function defineQuery<TData>(options: {
+  key: QueryKey$1;
+  query?: () => Promise<TData>;
+  queryFn?: () => Promise<TData>;
+  staleTime?: number;
+  gcTime?: number;
+}): () => _tanstack_vue_query0.UseQueryReturnType<TData, Error>;
+//#endregion
+//#region src/define-mutation.d.ts
+/**
+ * Options for defineMutation
+ */
+interface MutationOptions<TData, TVariables, TError = Error> {
+  /** The mutation function that performs the actual operation */
+  mutation: (variables: TVariables) => Promise<TData>;
+  /** Called on successful mutation */
+  onSuccess?: (data: TData, variables: TVariables) => void;
+  /** Called on mutation error */
+  onError?: (error: TError, variables: TVariables) => void;
+  /** Called after mutation settles (success or error) */
+  onSettled?: (data: TData | undefined, error: TError | null, variables: TVariables) => void;
+}
+/**
+ * Define a reusable mutation composable (Pinia Colada style)
+ *
+ * Creates a composable that can be imported and used across multiple components.
+ * The mutation configuration is defined once and reused everywhere.
+ *
+ * @example
+ * ```ts
+ * // Define the mutation
+ * export const useCreatePost = defineMutation({
+ *   mutation: (data: { title: string; body: string }) => api.posts.create(data),
+ *   onSuccess: (data, variables) => {
+ *     queryClient.invalidateQueries({ queryKey: ['posts'] })
+ *   },
+ * })
+ *
+ * // Use in component
+ * const { mutate, mutateAsync, isPending } = useCreatePost()
+ * mutate({ title: 'New Post', body: 'Content...' })
+ * ```
+ */
+declare function defineMutation<TData, TVariables, TError = Error>(options: MutationOptions<TData, TVariables, TError>): () => _tanstack_vue_query0.UseMutationReturnType<TData, TError, TVariables, unknown, Omit<_tanstack_vue_query0.MutationObserverIdleResult<TData, TError, TVariables, unknown>, "mutate" | "reset"> | Omit<_tanstack_vue_query0.MutationObserverLoadingResult<TData, TError, TVariables, unknown>, "mutate" | "reset"> | Omit<_tanstack_vue_query0.MutationObserverErrorResult<TData, TError, TVariables, unknown>, "mutate" | "reset"> | Omit<_tanstack_vue_query0.MutationObserverSuccessResult<TData, TError, TVariables, unknown>, "mutate" | "reset">>;
+//#endregion
+//#region src/query-keys.d.ts
+/**
+ * Result type for a query key factory
+ */
+type QueryKeyFactoryResult<TRoot extends string, TKeys extends Record<string, ((arg: never) => unknown) | null>> = {
+  all: () => readonly [TRoot];
+} & { [K in keyof TKeys]: TKeys[K] extends null ? () => readonly [TRoot, K] : TKeys[K] extends ((arg: infer A) => infer R) ? (arg: A) => readonly [TRoot, K, R] : never };
+/**
+ * Create a type-safe query key factory
+ *
+ * Creates a factory object with methods that generate consistent, hierarchical
+ * query keys. This helps maintain cache invalidation patterns and ensures
+ * type safety across your application.
+ *
+ * @example
+ * ```ts
+ * export const postKeys = createQueryKeyFactory('posts', {
+ *   lists: null,                              // () => ['posts', 'lists']
+ *   list: (filters: { page: number }) => filters,  // (f) => ['posts', 'list', f]
+ *   details: null,                            // () => ['posts', 'details']
+ *   detail: (id: string) => id,               // (id) => ['posts', 'detail', id]
+ * })
+ *
+ * // Usage
+ * postKeys.all()             // ['posts']
+ * postKeys.lists()           // ['posts', 'lists']
+ * postKeys.list({ page: 1 }) // ['posts', 'list', { page: 1 }]
+ * postKeys.detail('123')     // ['posts', 'detail', '123']
+ *
+ * // Invalidation example
+ * queryClient.invalidateQueries({ queryKey: postKeys.all() })
+ * ```
+ */
+declare function createQueryKeyFactory<TRoot extends string, TKeys extends Record<string, ((arg: never) => unknown) | null>>(root: TRoot, keys: TKeys): QueryKeyFactoryResult<TRoot, TKeys>;
+//#endregion
+//#region src/defer.d.ts
+/**
+ * Query options compatible with defer functions
+ */
+interface DeferrableQueryOptions {
+  queryKey: QueryKey$1;
+  queryFn: () => Promise<unknown>;
+  staleTime?: number;
+  gcTime?: number;
+}
+/**
+ * Start fetching queries without blocking navigation (fire-and-forget).
+ *
+ * Use this in route loaders for non-critical data. The queries will start
+ * fetching in the background, and components using useSuspenseQuery will
+ * suspend until the data is ready.
+ *
+ * @example
+ * ```ts
+ * export const Route = createFileRoute('/users/:userId')({
+ *   loader: async ({ params, context }) => {
+ *     const { queryClient } = context
+ *
+ *     // Critical - blocks navigation until ready
+ *     await queryClient.ensureQueryData(userQuery(params.userId))
+ *
+ *     // Deferred - starts fetching without blocking navigation
+ *     defer(queryClient,
+ *       userActivityQuery(params.userId),
+ *       userRecommendationsQuery(params.userId),
+ *     )
+ *   },
+ * })
+ * ```
+ */
+declare function defer(queryClient: QueryClient$1, ...queries: DeferrableQueryOptions[]): void;
+/**
+ * Start fetching queries and return promises for optional awaiting.
+ *
+ * Unlike defer(), this returns the prefetch promises, allowing you to
+ * optionally await them later (e.g., for analytics or debugging).
+ *
+ * @example
+ * ```ts
+ * // Start fetching
+ * const promises = deferWithPromises(queryClient, slowQuery1, slowQuery2)
+ *
+ * // Continue with other work...
+ *
+ * // Later, if you need to know when they complete:
+ * await Promise.all(promises)
+ * ```
+ */
+declare function deferWithPromises(queryClient: QueryClient$1, ...queries: DeferrableQueryOptions[]): Promise<void>[];
+//#endregion
+//#region src/suspense.d.ts
+/**
+ * Infer TData from QueryOptionsOutput
+ */
+type InferQueryData<T> = T extends QueryOptionsOutput<infer TData, QueryKey$1> ? TData : never;
+/**
+ * Return type for useSuspenseQuery with guaranteed data (not undefined after suspense resolves)
+ */
+interface UseSuspenseQueryResult<TData> {
+  data: Ref<TData>;
+  error: Ref<Error | null>;
+  isLoading: Ref<boolean>;
+  isFetching: Ref<boolean>;
+  isError: Ref<boolean>;
+  isSuccess: Ref<boolean>;
+  refetch: () => Promise<TData>;
+}
+/**
+ * Suspense-compatible query hook for Vue.
+ *
+ * Returns a Promise that resolves to the query result when data is ready.
+ * Use with top-level await in <script setup> to trigger Suspense.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useSuspenseQuery } from '@kimesh/query'
+ * import { postsQuery } from './posts.data'
+ *
+ * // Awaiting triggers Suspense - component suspends until data ready
+ * // data is typed as Ref<Post[]> (not Ref<Post[] | undefined>)
+ * const { data: posts } = await useSuspenseQuery(postsQuery)
+ * </script>
+ *
+ * <template>
+ *   <div v-for="post in posts" :key="post.id">{{ post.title }}</div>
+ * </template>
+ * ```
+ */
+declare function useSuspenseQuery<T extends QueryOptionsOutput<unknown, QueryKey$1>>(options: T): Promise<UseSuspenseQueryResult<InferQueryData<T>>>;
+/**
+ * Suspense-compatible infinite query hook for Vue.
+ *
+ * Note: This is a basic implementation. For full infinite query support,
+ * you may need to extend the options interface to include initialPageParam
+ * and getNextPageParam configuration.
+ */
+declare function useSuspenseInfiniteQuery<T extends QueryOptionsOutput<unknown, QueryKey$1>>(options: T): Promise<UseInfiniteQueryReturnType<InferQueryData<T>, Error>>;
+type UseSuspenseQueryReturnType<TData = unknown> = UseSuspenseQueryResult<TData>;
+//#endregion
+export { $fetch, type DeferrableQueryOptions, type FetchContext, type FetchError, type FetchPluginOptions, type FetchResponse, type FetchRuntimeConfig, KimeshQueryPlugin, type KimeshQueryPluginOptions, type KmAsyncDataContext, type KmAsyncDataResult, type KmFetchCreateOptions, type KmFetchInstance, type KmFetchRequestOptions, type LayerFetchPluginOptions, type LoadableComponent, type LoaderDefinition, QueryClient, type QueryKey, type QueryKeyFactory, type QueryPrefetchOptions, type UseKmAsyncDataOptions, type UseKmFetchOptions, type UseQueryReturnType, type UseSuspenseQueryReturnType, VueQueryPlugin, createKimeshQueryClient, createKmFetch, createNamedFetchPlugin, createPrefetcher, createQueryKeyFactory, defer, deferWithPromises, defineMutation, defineQuery, defineQueryOptions, executeLoader, extractLoaders, fetchPlugin, getCurrentLayer, getLayerFetch, hasLoader, initGlobalFetch, initLayerFetch, isLayerFetchInitialized, layerFetchPlugin, queryOptions, setCurrentLayer, setupQueryPrefetching, useGlobalFetch, useInfiniteQuery, useKmAsyncData, useKmData, useKmFetch, useLazyKmAsyncData, useLazyKmFetch, useMutation, useQuery, useQueryClient, useSuspenseInfiniteQuery, useSuspenseQuery };
+//# sourceMappingURL=index.d.mts.map