@demokit-ai/tanstack-query 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,432 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { QueryKey as QueryKey$1, QueryClient, UseMutationOptions, UseMutationResult, QueryClientConfig } from '@tanstack/react-query';
+import { QueryKey, QueryKeyMatchResult } from '@demokit-ai/core';
+export { matchQueryKey } from '@demokit-ai/core';
+import { ReactNode } from 'react';
+
+/**
+ * Context provided to query fixture handlers
+ */
+interface QueryFixtureContext {
+    /**
+     * The full query key
+     */
+    queryKey: QueryKey$1;
+    /**
+     * Extracted parameters from pattern matching
+     */
+    params: Record<string, unknown>;
+    /**
+     * The match result from pattern matching
+     */
+    match: QueryKeyMatchResult;
+    /**
+     * Signal for aborting the query
+     */
+    signal?: AbortSignal;
+}
+/**
+ * A query fixture handler can be:
+ * - A static value (object, array, primitive)
+ * - A function that receives context and returns data
+ * - An async function for dynamic fixtures
+ */
+type QueryFixtureHandler<TData = unknown> = TData | ((context: QueryFixtureContext) => TData) | ((context: QueryFixtureContext) => Promise<TData>);
+/**
+ * Map of query key patterns to fixture handlers
+ */
+type QueryFixtureMap = Map<QueryKey, QueryFixtureHandler>;
+/**
+ * Context provided to mutation fixture handlers
+ */
+interface MutationFixtureContext<TVariables = unknown> {
+    /**
+     * The mutation key (if defined)
+     */
+    mutationKey?: QueryKey$1;
+    /**
+     * Variables passed to the mutation
+     */
+    variables: TVariables;
+    /**
+     * The query client for cache manipulation
+     */
+    queryClient: QueryClient;
+}
+/**
+ * A mutation fixture handler
+ */
+type MutationFixtureHandler<TData = unknown, TVariables = unknown> = TData | ((context: MutationFixtureContext<TVariables>) => TData) | ((context: MutationFixtureContext<TVariables>) => Promise<TData>);
+/**
+ * Map of mutation keys to fixture handlers
+ */
+type MutationFixtureMap = Map<string, MutationFixtureHandler>;
+/**
+ * Configuration for DemoQueryProvider
+ */
+interface DemoQueryProviderConfig {
+    /**
+     * Query fixtures - map of query key patterns to handlers
+     */
+    queries?: QueryFixtureMap | QueryFixtureMapObject;
+    /**
+     * Mutation fixtures - map of mutation names to handlers
+     */
+    mutations?: MutationFixtureMap | MutationFixtureMapObject;
+    /**
+     * Whether demo mode is enabled
+     * If not provided, reads from DemoKitProvider context
+     */
+    enabled?: boolean;
+    /**
+     * Delay in ms before returning fixture data (simulates network latency)
+     * @default 0
+     */
+    delay?: number;
+    /**
+     * Whether to pre-populate the query cache on mount
+     * Only applies to fixtures with static values (not functions)
+     * @default false
+     */
+    prepopulateCache?: boolean;
+    /**
+     * Fallback query function for unmatched queries
+     * If not provided, will use fetch-based approach
+     */
+    fallbackQueryFn?: (context: {
+        queryKey: QueryKey$1;
+        signal?: AbortSignal;
+    }) => Promise<unknown>;
+    /**
+     * staleTime for demo queries
+     * @default Infinity
+     */
+    staleTime?: number;
+}
+/**
+ * Object-based query fixture map (easier to define)
+ * Keys are JSON-stringified query key patterns
+ */
+type QueryFixtureMapObject = Record<string, QueryFixtureHandler>;
+/**
+ * Object-based mutation fixture map
+ */
+type MutationFixtureMapObject = Record<string, MutationFixtureHandler>;
+/**
+ * Props for DemoQueryProvider
+ */
+interface DemoQueryProviderProps extends DemoQueryProviderConfig {
+    /**
+     * Child components
+     */
+    children: ReactNode;
+    /**
+     * Existing QueryClient to wrap
+     * If not provided, creates a new one
+     */
+    client?: QueryClient;
+}
+/**
+ * Return type of useDemoQuery hook
+ */
+interface DemoQueryState {
+    /**
+     * Whether demo mode is enabled
+     */
+    isDemoMode: boolean;
+    /**
+     * Add or update a query fixture
+     */
+    setQueryFixture: (pattern: QueryKey, handler: QueryFixtureHandler) => void;
+    /**
+     * Remove a query fixture
+     */
+    removeQueryFixture: (pattern: QueryKey) => void;
+    /**
+     * Add or update a mutation fixture
+     */
+    setMutationFixture: (name: string, handler: MutationFixtureHandler) => void;
+    /**
+     * Remove a mutation fixture
+     */
+    removeMutationFixture: (name: string) => void;
+    /**
+     * Invalidate all demo queries (triggers refetch)
+     */
+    invalidateAll: () => void;
+    /**
+     * Reset query cache to initial demo state
+     */
+    resetCache: () => void;
+}
+
+/**
+ * Provider component for DemoKit TanStack Query integration
+ *
+ * Wraps QueryClientProvider and intercepts queries when demo mode is enabled.
+ *
+ * @example
+ * // With new QueryClient
+ * <DemoQueryProvider
+ *   queries={{
+ *     '["users"]': [{ id: '1', name: 'Demo User' }],
+ *     '["users", ":id"]': ({ params }) => ({ id: params.id, name: 'Demo User' }),
+ *   }}
+ * >
+ *   <App />
+ * </DemoQueryProvider>
+ *
+ * @example
+ * // With existing QueryClient
+ * const queryClient = new QueryClient()
+ *
+ * <DemoQueryProvider client={queryClient} queries={...}>
+ *   <App />
+ * </DemoQueryProvider>
+ *
+ * @example
+ * // With DemoKitProvider (auto-detects demo mode)
+ * <DemoKitProvider fixtures={...}>
+ *   <DemoQueryProvider queries={...}>
+ *     <App />
+ *   </DemoQueryProvider>
+ * </DemoKitProvider>
+ */
+declare function DemoQueryProvider({ children, client, ...config }: DemoQueryProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Hook to access DemoQuery state and controls
+ *
+ * @returns DemoQuery context value
+ * @throws Error if used outside of DemoQueryProvider
+ *
+ * @example
+ * function MyComponent() {
+ *   const { isDemoMode, setQueryFixture, invalidateAll } = useDemoQuery()
+ *
+ *   // Dynamically add a fixture
+ *   const handleAddFixture = () => {
+ *     setQueryFixture(['users', 'custom'], { id: 'custom', name: 'Custom User' })
+ *     invalidateAll() // Trigger refetch
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleAddFixture}>Add Custom Fixture</button>
+ *   )
+ * }
+ */
+declare function useDemoQuery(): DemoQueryState;
+/**
+ * Hook to check if demo mode is enabled
+ * Shorthand for useDemoQuery().isDemoMode
+ *
+ * @example
+ * function MyComponent() {
+ *   const isDemoMode = useIsDemoQueryMode()
+ *
+ *   return isDemoMode ? <DemoBadge /> : null
+ * }
+ */
+declare function useIsDemoQueryMode(): boolean;
+
+/**
+ * Options for useDemoMutation hook
+ */
+interface UseDemoMutationOptions<TData, TError, TVariables, TContext> extends Omit<UseMutationOptions<TData, TError, TVariables, TContext>, 'mutationFn'> {
+    /**
+     * The real mutation function to use when demo mode is disabled
+     */
+    mutationFn: (variables: TVariables) => Promise<TData>;
+    /**
+     * Name used to look up the demo fixture
+     * If not provided, uses mutationKey as string
+     */
+    demoName?: string;
+    /**
+     * Demo fixture handler for this mutation
+     * If provided, overrides the fixture from DemoQueryProvider
+     */
+    demoFixture?: MutationFixtureHandler<TData, TVariables>;
+    /**
+     * Delay in ms before returning demo data
+     * @default 0
+     */
+    demoDelay?: number;
+}
+/**
+ * A mutation hook that automatically uses demo fixtures when demo mode is enabled
+ *
+ * @example
+ * const createUser = useDemoMutation({
+ *   mutationFn: async (data) => api.createUser(data),
+ *   demoName: 'createUser',
+ *   demoFixture: ({ variables, queryClient }) => {
+ *     // Create demo user
+ *     const newUser = { id: crypto.randomUUID(), ...variables }
+ *
+ *     // Update the users query cache
+ *     queryClient.setQueryData(['users'], (old: User[] = []) => [...old, newUser])
+ *
+ *     return newUser
+ *   },
+ *   onSuccess: (data) => {
+ *     console.log('Created user:', data)
+ *   },
+ * })
+ *
+ * // Use like normal useMutation
+ * createUser.mutate({ name: 'New User', email: 'user@example.com' })
+ */
+declare function useDemoMutation<TData = unknown, TError = unknown, TVariables = void, TContext = unknown>(options: UseDemoMutationOptions<TData, TError, TVariables, TContext>): UseMutationResult<TData, TError, TVariables, TContext>;
+/**
+ * Create a set of demo mutations with fixtures
+ *
+ * @example
+ * const mutations = createDemoMutations({
+ *   createUser: {
+ *     mutationFn: api.createUser,
+ *     fixture: ({ variables, queryClient }) => {
+ *       const newUser = { id: 'demo-1', ...variables }
+ *       queryClient.setQueryData(['users'], (old = []) => [...old, newUser])
+ *       return newUser
+ *     },
+ *   },
+ *   deleteUser: {
+ *     mutationFn: api.deleteUser,
+ *     fixture: ({ variables, queryClient }) => {
+ *       queryClient.setQueryData(['users'], (old: User[] = []) =>
+ *         old.filter(u => u.id !== variables.id)
+ *       )
+ *       return { success: true }
+ *     },
+ *   },
+ * })
+ *
+ * // Use in components
+ * const { createUser, deleteUser } = mutations
+ */
+type DemoMutationConfig<TData, TVariables> = {
+    mutationFn: (variables: TVariables) => Promise<TData>;
+    fixture: MutationFixtureHandler<TData, TVariables>;
+    delay?: number;
+};
+/**
+ * Helper to create mutation options with demo fixture
+ */
+declare function createMutationOptions<TData, TVariables>(config: DemoMutationConfig<TData, TVariables>): Pick<UseDemoMutationOptions<TData, unknown, TVariables, unknown>, 'mutationFn' | 'demoFixture' | 'demoDelay'>;
+
+/**
+ * Configuration for creating a demo-aware QueryClient
+ */
+interface DemoQueryClientConfig extends DemoQueryProviderConfig {
+    /**
+     * Base QueryClient config to extend
+     */
+    queryClientConfig?: QueryClientConfig;
+}
+/**
+ * Create a demo-aware query function
+ *
+ * This wraps the default query function to intercept demo queries
+ * and return fixture data when demo mode is enabled.
+ */
+declare function createDemoQueryFn(config: {
+    fixtures: QueryFixtureMap;
+    delay?: number;
+    fallbackQueryFn?: DemoQueryProviderConfig['fallbackQueryFn'];
+    isEnabled: () => boolean;
+}): ({ queryKey, signal, }: {
+    queryKey: readonly unknown[];
+    signal?: AbortSignal;
+}) => Promise<any>;
+/**
+ * Create a demo-aware QueryClient
+ *
+ * This creates a QueryClient configured to intercept queries when demo mode
+ * is enabled and return fixture data instead of making real API calls.
+ *
+ * @example
+ * const { client, enable, disable, isEnabled } = createDemoQueryClient({
+ *   queries: {
+ *     '["users"]': [{ id: '1', name: 'Demo User' }],
+ *     '["users", ":id"]': ({ params }) => ({ id: params.id, name: 'Demo User' }),
+ *   },
+ *   delay: 100, // Simulate 100ms latency
+ * })
+ *
+ * // Use with QueryClientProvider
+ * <QueryClientProvider client={client}>
+ *   <App />
+ * </QueryClientProvider>
+ */
+declare function createDemoQueryClient(config?: DemoQueryClientConfig): {
+    /**
+     * The QueryClient instance
+     */
+    client: QueryClient;
+    /**
+     * Enable demo mode
+     */
+    enable: () => void;
+    /**
+     * Disable demo mode
+     */
+    disable: () => void;
+    /**
+     * Check if demo mode is enabled
+     */
+    isEnabled: () => boolean;
+    /**
+     * Get the fixture map
+     */
+    getFixtures: () => QueryFixtureMap;
+    /**
+     * Add or update a fixture
+     */
+    setFixture: (pattern: QueryKey, handler: QueryFixtureHandler) => void;
+    /**
+     * Remove a fixture
+     */
+    removeFixture: (pattern: QueryKey) => void;
+    /**
+     * Clear all query cache
+     */
+    clearCache: () => void;
+    /**
+     * Invalidate all queries
+     */
+    invalidateAll: () => void;
+};
+type DemoQueryClient = ReturnType<typeof createDemoQueryClient>;
+
+/**
+ * Convert TanStack Query key to DemoKit QueryKey
+ * TanStack Query keys can contain any value, so we normalize them
+ */
+declare function normalizeQueryKey(queryKey: QueryKey$1): QueryKey;
+/**
+ * Parse a JSON string pattern into a QueryKey
+ * Handles both array notation and simple string patterns
+ *
+ * @example
+ * parsePatternString('["users"]') // ['users']
+ * parsePatternString('["users", ":id"]') // ['users', ':id']
+ * parsePatternString('users') // ['users']
+ */
+declare function parsePatternString(pattern: string): QueryKey;
+/**
+ * Convert object-based fixture map to Map-based fixture map
+ */
+declare function normalizeFixtureMap(fixtures: QueryFixtureMapObject | QueryFixtureMap): QueryFixtureMap;
+/**
+ * Find a matching fixture for a query key
+ *
+ * @param fixtures - Map of query key patterns to handlers
+ * @param queryKey - The query key to match
+ * @returns Tuple of [handler, match result] or null if no match
+ */
+declare function findMatchingFixture(fixtures: QueryFixtureMap, queryKey: QueryKey$1): [QueryFixtureHandler, {
+    params: Record<string, unknown>;
+}] | null;
+
+export { type DemoMutationConfig, type DemoQueryClient, DemoQueryProvider, type DemoQueryProviderConfig, type DemoQueryProviderProps, type DemoQueryState, type MutationFixtureContext, type MutationFixtureHandler, type MutationFixtureMap, type MutationFixtureMapObject, type QueryFixtureContext, type QueryFixtureHandler, type QueryFixtureMap, type QueryFixtureMapObject, type UseDemoMutationOptions, createDemoQueryClient, createDemoQueryFn, createMutationOptions, findMatchingFixture, normalizeFixtureMap, normalizeQueryKey, parsePatternString, useDemoMutation, useDemoQuery, useIsDemoQueryMode };