@demokit-ai/swr 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,415 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { MutatorCallback, MutatorOptions, SWRConfiguration, Middleware } from 'swr';
+import { QueryKey, QueryKeyMatchResult } from '@demokit-ai/core';
+export { matchQueryKey } from '@demokit-ai/core';
+import { ReactNode } from 'react';
+import { SWRMutationConfiguration, SWRMutationResponse } from 'swr/mutation';
+
+/**
+ * Context provided to SWR fixture handlers
+ */
+interface SWRFixtureContext {
+    /**
+     * The SWR key (can be string, array, or object)
+     */
+    key: string | unknown[];
+    /**
+     * Normalized key as QueryKey for pattern matching
+     */
+    normalizedKey: QueryKey;
+    /**
+     * Extracted parameters from pattern matching
+     */
+    params: Record<string, unknown>;
+    /**
+     * The match result from pattern matching
+     */
+    match: QueryKeyMatchResult;
+}
+/**
+ * A 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 SWRFixtureHandler<TData = unknown> = TData | ((context: SWRFixtureContext) => TData) | ((context: SWRFixtureContext) => Promise<TData>);
+/**
+ * Map of key patterns to fixture handlers
+ */
+type SWRFixtureMap = Map<QueryKey, SWRFixtureHandler>;
+/**
+ * Object-based fixture map (easier to define)
+ * Keys are JSON-stringified key patterns or simple strings
+ */
+type SWRFixtureMapObject = Record<string, SWRFixtureHandler>;
+/**
+ * Context provided to mutation fixture handlers
+ */
+interface SWRMutationFixtureContext<TData = unknown, TArg = unknown> {
+    /**
+     * The mutation key
+     */
+    key: string | unknown[];
+    /**
+     * The argument passed to the mutation
+     */
+    arg: TArg;
+    /**
+     * Current data in the cache
+     */
+    currentData: TData | undefined;
+    /**
+     * Function to mutate other SWR keys
+     */
+    mutate: <T>(key: string | unknown[], data?: T | Promise<T> | MutatorCallback<T>, opts?: boolean | MutatorOptions<T>) => Promise<T | undefined>;
+}
+/**
+ * A mutation fixture handler
+ */
+type SWRMutationFixtureHandler<TData = unknown, TArg = unknown> = TData | ((context: SWRMutationFixtureContext<TData, TArg>) => TData) | ((context: SWRMutationFixtureContext<TData, TArg>) => Promise<TData>);
+/**
+ * Map of mutation keys to fixture handlers
+ */
+type SWRMutationFixtureMap = Map<string, SWRMutationFixtureHandler>;
+/**
+ * Object-based mutation fixture map
+ */
+type SWRMutationFixtureMapObject = Record<string, SWRMutationFixtureHandler>;
+/**
+ * Configuration for DemoSWRProvider
+ */
+interface DemoSWRProviderConfig {
+    /**
+     * Fixtures - map of key patterns to handlers
+     */
+    fixtures?: SWRFixtureMap | SWRFixtureMapObject;
+    /**
+     * Mutation fixtures - map of mutation names to handlers
+     */
+    mutations?: SWRMutationFixtureMap | SWRMutationFixtureMapObject;
+    /**
+     * Whether demo mode is enabled
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Delay in ms before returning fixture data (simulates network latency)
+     * @default 0
+     */
+    delay?: number;
+    /**
+     * Fallback data to use for SWR's fallback option
+     * Will be merged with any static fixture values
+     */
+    fallback?: Record<string, unknown>;
+    /**
+     * Additional SWR configuration to merge
+     */
+    swrConfig?: SWRConfiguration;
+}
+/**
+ * Props for DemoSWRProvider
+ */
+interface DemoSWRProviderProps extends DemoSWRProviderConfig {
+    /**
+     * Child components
+     */
+    children: ReactNode;
+}
+/**
+ * Return type of useDemoSWR hook
+ */
+interface DemoSWRState {
+    /**
+     * Whether demo mode is enabled
+     */
+    isDemoMode: boolean;
+    /**
+     * Add or update a fixture
+     */
+    setFixture: (pattern: QueryKey, handler: SWRFixtureHandler) => void;
+    /**
+     * Remove a fixture
+     */
+    removeFixture: (pattern: QueryKey) => void;
+    /**
+     * Add or update a mutation fixture
+     */
+    setMutationFixture: (name: string, handler: SWRMutationFixtureHandler) => void;
+    /**
+     * Remove a mutation fixture
+     */
+    removeMutationFixture: (name: string) => void;
+    /**
+     * Get the demo-aware fetcher function
+     */
+    getFetcher: () => <T>(key: string | unknown[]) => Promise<T>;
+    /**
+     * Get the demo middleware
+     */
+    getMiddleware: () => Middleware;
+}
+
+/**
+ * Provider component for DemoKit SWR integration
+ *
+ * Wraps SWRConfig and intercepts fetches when demo mode is enabled.
+ * Uses SWR's middleware pattern for maximum flexibility.
+ *
+ * @example
+ * // With object-based fixtures
+ * <DemoSWRProvider
+ *   enabled={true}
+ *   fixtures={{
+ *     '/api/users': [{ id: '1', name: 'Demo User' }],
+ *     '["/api/users", ":id"]': ({ params }) => ({ id: params.id, name: 'Demo User' }),
+ *     '["/api/projects", { status: ":status" }]': ({ params }) => [
+ *       { id: '1', name: 'Project', status: params.status },
+ *     ],
+ *   }}
+ *   delay={100}
+ * >
+ *   <App />
+ * </DemoSWRProvider>
+ *
+ * @example
+ * // With Map-based fixtures
+ * const fixtures = new Map([
+ *   [['/api/users'], [{ id: '1', name: 'Demo User' }]],
+ *   [['/api/users', ':id'], ({ params }) => ({ id: params.id, name: 'Demo User' })],
+ * ])
+ *
+ * <DemoSWRProvider enabled={true} fixtures={fixtures}>
+ *   <App />
+ * </DemoSWRProvider>
+ *
+ * @example
+ * // With cache seeding via fallback
+ * <DemoSWRProvider
+ *   enabled={true}
+ *   fixtures={fixtures}
+ *   fallback={{
+ *     '/api/users': [{ id: '1', name: 'Pre-loaded User' }],
+ *   }}
+ * >
+ *   <App />
+ * </DemoSWRProvider>
+ */
+declare function DemoSWRProvider({ children, fixtures, mutations, enabled, delay, fallback, swrConfig, }: DemoSWRProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Hook to access DemoSWR state and controls
+ *
+ * @returns DemoSWR context value
+ * @throws Error if used outside of DemoSWRProvider
+ *
+ * @example
+ * function MyComponent() {
+ *   const { isDemoMode, setFixture } = useDemoSWR()
+ *
+ *   // Dynamically add a fixture
+ *   const handleAddFixture = () => {
+ *     setFixture(['/api/users', 'custom'], { id: 'custom', name: 'Custom User' })
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleAddFixture}>Add Custom Fixture</button>
+ *   )
+ * }
+ */
+declare function useDemoSWR(): DemoSWRState;
+/**
+ * Hook to check if demo mode is enabled
+ * Shorthand for useDemoSWR().isDemoMode
+ *
+ * @example
+ * function MyComponent() {
+ *   const isDemoMode = useIsDemoSWRMode()
+ *
+ *   return isDemoMode ? <DemoBadge /> : null
+ * }
+ */
+declare function useIsDemoSWRMode(): boolean;
+/**
+ * Options for useDemoSWRMutation hook
+ */
+interface UseDemoSWRMutationOptions<TData, TError, TArg> extends Omit<SWRMutationConfiguration<TData, TError, string, TArg>, 'fetcher'> {
+    /**
+     * The real mutation function to use when demo mode is disabled
+     */
+    fetcher: (key: string, options: {
+        arg: TArg;
+    }) => Promise<TData>;
+    /**
+     * Demo fixture handler for this mutation
+     */
+    demoFixture?: SWRMutationFixtureHandler<TData, TArg>;
+    /**
+     * Delay in ms before returning demo data
+     * @default 0
+     */
+    demoDelay?: number;
+}
+/**
+ * A mutation hook that automatically uses demo fixtures when demo mode is enabled
+ *
+ * Works with useSWRMutation from swr/mutation.
+ *
+ * @example
+ * const { trigger: createUser, isMutating } = useDemoSWRMutation('/api/users', {
+ *   fetcher: async (key, { arg }) => api.createUser(arg),
+ *   demoFixture: ({ arg, mutate }) => {
+ *     // Create demo user
+ *     const newUser = { id: crypto.randomUUID(), ...arg }
+ *
+ *     // Update the users cache
+ *     mutate('/api/users', (current: User[] = []) => [...current, newUser])
+ *
+ *     return newUser
+ *   },
+ *   onSuccess: (data) => {
+ *     console.log('Created user:', data)
+ *   },
+ * })
+ *
+ * // Use like normal useSWRMutation
+ * createUser({ name: 'New User', email: 'user@example.com' })
+ */
+declare function useDemoSWRMutation<TData = unknown, TError = unknown, TArg = unknown>(key: string, options: UseDemoSWRMutationOptions<TData, TError, TArg>): SWRMutationResponse<TData, TError, string, TArg>;
+
+/**
+ * Options for creating a demo-aware fetcher
+ */
+interface CreateDemoFetcherOptions {
+    /**
+     * Map of key patterns to fixture handlers
+     */
+    fixtures: SWRFixtureMap;
+    /**
+     * Function to check if demo mode is enabled
+     */
+    isEnabled: () => boolean;
+    /**
+     * Delay in ms before returning fixture data
+     * @default 0
+     */
+    delay?: number;
+    /**
+     * Fallback fetcher to use when demo mode is disabled
+     * or no fixture matches
+     */
+    fallbackFetcher?: <T>(key: string | unknown[]) => Promise<T>;
+}
+/**
+ * Create a demo-aware fetcher function for SWR
+ *
+ * This fetcher intercepts requests when demo mode is enabled
+ * and returns fixture data instead of making real API calls.
+ *
+ * @example
+ * const fixtures = new Map([
+ *   [['/api/users'], [{ id: '1', name: 'Demo User' }]],
+ *   [['/api/users', ':id'], ({ params }) => ({ id: params.id, name: 'User' })],
+ * ])
+ *
+ * const fetcher = createDemoFetcher({
+ *   fixtures,
+ *   isEnabled: () => isDemoMode,
+ *   delay: 100,
+ * })
+ *
+ * // Use with SWR
+ * const { data } = useSWR('/api/users', fetcher)
+ */
+declare function createDemoFetcher(options: CreateDemoFetcherOptions): <TData = unknown>(key: string | unknown[]) => Promise<TData>;
+/**
+ * Default fetcher that uses fetch API
+ * Used as fallback when demo mode is disabled
+ */
+declare function defaultFetcher<TData = unknown>(key: string | unknown[]): Promise<TData>;
+
+/**
+ * Options for creating the demo middleware
+ */
+interface CreateDemoMiddlewareOptions {
+    /**
+     * Map of key patterns to fixture handlers
+     */
+    fixtures: SWRFixtureMap;
+    /**
+     * Function to check if demo mode is enabled
+     */
+    isEnabled: () => boolean;
+    /**
+     * Delay in ms before returning fixture data
+     * @default 0
+     */
+    delay?: number;
+}
+/**
+ * Create a demo-aware SWR middleware
+ *
+ * This middleware intercepts SWR requests when demo mode is enabled
+ * and returns fixture data instead of using the original fetcher.
+ *
+ * @example
+ * import { SWRConfig } from 'swr'
+ * import { createDemoMiddleware } from '@demokit-ai/swr'
+ *
+ * const fixtures = new Map([
+ *   [['/api/users'], [{ id: '1', name: 'Demo User' }]],
+ *   [['/api/users', ':id'], ({ params }) => ({ id: params.id, name: 'User' })],
+ * ])
+ *
+ * const demoMiddleware = createDemoMiddleware({
+ *   fixtures,
+ *   isEnabled: () => isDemoMode,
+ *   delay: 100,
+ * })
+ *
+ * function App() {
+ *   return (
+ *     <SWRConfig value={{ use: [demoMiddleware] }}>
+ *       <YourApp />
+ *     </SWRConfig>
+ *   )
+ * }
+ */
+declare function createDemoMiddleware(options: CreateDemoMiddlewareOptions): Middleware;
+
+/**
+ * Normalize an SWR key to a QueryKey for matching
+ *
+ * SWR keys can be:
+ * - Strings: '/api/users' -> ['/api/users']
+ * - Arrays: ['/api/users', id] -> ['/api/users', id]
+ * - Functions that return keys (not handled here)
+ */
+declare function normalizeKey(key: string | unknown[]): QueryKey;
+/**
+ * Parse a JSON string pattern into a QueryKey
+ * Handles both array notation and simple string patterns
+ *
+ * @example
+ * parsePatternString('["/api/users"]') // ['/api/users']
+ * parsePatternString('["/api/users", ":id"]') // ['/api/users', ':id']
+ * parsePatternString('/api/users') // ['/api/users']
+ */
+declare function parsePatternString(pattern: string): QueryKey;
+/**
+ * Convert object-based fixture map to Map-based fixture map
+ */
+declare function normalizeFixtureMap(fixtures: SWRFixtureMapObject | SWRFixtureMap): SWRFixtureMap;
+/**
+ * Find a matching fixture for an SWR key
+ *
+ * @param fixtures - Map of key patterns to handlers
+ * @param key - The SWR key to match
+ * @returns Tuple of [handler, match result] or null if no match
+ */
+declare function findMatchingFixture(fixtures: SWRFixtureMap, key: string | unknown[]): [SWRFixtureHandler, {
+    params: Record<string, unknown>;
+    normalizedKey: QueryKey;
+}] | null;
+
+export { type CreateDemoFetcherOptions, type CreateDemoMiddlewareOptions, DemoSWRProvider, type DemoSWRProviderConfig, type DemoSWRProviderProps, type DemoSWRState, type SWRFixtureContext, type SWRFixtureHandler, type SWRFixtureMap, type SWRFixtureMapObject, type SWRMutationFixtureContext, type SWRMutationFixtureHandler, type SWRMutationFixtureMap, type SWRMutationFixtureMapObject, type UseDemoSWRMutationOptions, createDemoFetcher, createDemoMiddleware, defaultFetcher, findMatchingFixture, normalizeFixtureMap, normalizeKey, parsePatternString, useDemoSWR, useDemoSWRMutation, useIsDemoSWRMode };