@veloxts/client 0.4.1 → 0.4.3

package/dist/react/provider.js

@@ -0,0 +1,162 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * VeloxProvider - React context provider for VeloxTS client
+ *
+ * Wraps your React application to provide access to the VeloxTS client
+ * and React Query's QueryClient.
+ *
+ * @module @veloxts/client/react/provider
+ */
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { createContext, useContext, useMemo } from 'react';
+import { createClient } from '../client.js';
+// ============================================================================
+// Context
+// ============================================================================
+/**
+ * Internal context for VeloxTS client
+ *
+ * Typed as `unknown` at creation time since the router type
+ * is provided by the consumer via generic parameter.
+ */
+const VeloxContext = createContext(null);
+// ============================================================================
+// Default QueryClient
+// ============================================================================
+/**
+ * Creates a default QueryClient with sensible defaults for VeloxTS
+ */
+function createDefaultQueryClient() {
+    return new QueryClient({
+        defaultOptions: {
+            queries: {
+                staleTime: 30_000, // 30 seconds
+                retry: 1,
+                refetchOnWindowFocus: false,
+            },
+            mutations: {
+                retry: 0,
+            },
+        },
+    });
+}
+// ============================================================================
+// Provider Component
+// ============================================================================
+/**
+ * Provider component that sets up VeloxTS client and React Query
+ *
+ * This provider:
+ * - Creates a memoized VeloxTS client instance from the provided config
+ * - Sets up React Query's QueryClientProvider
+ * - Makes the client available to hooks via React context
+ *
+ * @template TRouter - The router type defining your procedure collections
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { VeloxProvider } from '@veloxts/client/react';
+ * import type { userProcedures, postProcedures } from './server/procedures';
+ *
+ * type AppRouter = {
+ *   users: typeof userProcedures;
+ *   posts: typeof postProcedures;
+ * };
+ *
+ * function App() {
+ *   return (
+ *     <VeloxProvider<AppRouter> config={{ baseUrl: '/api' }}>
+ *       <YourApp />
+ *     </VeloxProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example With custom QueryClient
+ * ```tsx
+ * import { QueryClient } from '@tanstack/react-query';
+ *
+ * const queryClient = new QueryClient({
+ *   defaultOptions: {
+ *     queries: { staleTime: 60_000 },
+ *   },
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <VeloxProvider<AppRouter>
+ *       config={{ baseUrl: '/api' }}
+ *       queryClient={queryClient}
+ *     >
+ *       <YourApp />
+ *     </VeloxProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example With custom headers
+ * ```tsx
+ * function App() {
+ *   const token = useAuthToken();
+ *
+ *   const config = useMemo(() => ({
+ *     baseUrl: '/api',
+ *     headers: {
+ *       Authorization: `Bearer ${token}`,
+ *     },
+ *   }), [token]);
+ *
+ *   return (
+ *     <VeloxProvider<AppRouter> config={config}>
+ *       <YourApp />
+ *     </VeloxProvider>
+ *   );
+ * }
+ * ```
+ */
+export function VeloxProvider({ children, config, queryClient: providedQueryClient, }) {
+    // Create client instance, memoized based on config reference
+    // Users should memoize their config object if they need to prevent re-renders
+    const client = useMemo(() => createClient(config), [config]);
+    // Use provided QueryClient or create default
+    // Only create once to avoid query state loss
+    const queryClient = useMemo(() => providedQueryClient ?? createDefaultQueryClient(), [providedQueryClient]);
+    // Memoize context value to prevent unnecessary re-renders
+    const contextValue = useMemo(() => ({ client }), [client]);
+    return (_jsx(VeloxContext.Provider, { value: contextValue, children: _jsx(QueryClientProvider, { client: queryClient, children: children }) }));
+}
+// ============================================================================
+// Context Hook
+// ============================================================================
+/**
+ * Hook to access VeloxTS client from context
+ *
+ * This is primarily used internally by useQuery and useMutation hooks,
+ * but can also be used directly for advanced use cases.
+ *
+ * @template TRouter - The router type for type-safe client access
+ * @returns The context value containing the typed client
+ * @throws Error if used outside of VeloxProvider
+ *
+ * @example Direct client access (advanced)
+ * ```tsx
+ * function MyComponent() {
+ *   const { client } = useVeloxContext<AppRouter>();
+ *
+ *   // Direct client access for edge cases
+ *   const handleClick = async () => {
+ *     const user = await client.users.getUser({ id: '123' });
+ *     console.log(user);
+ *   };
+ * }
+ * ```
+ */
+export function useVeloxContext() {
+    const context = useContext(VeloxContext);
+    if (!context) {
+        throw new Error('useVeloxContext must be used within a VeloxProvider. ' +
+            'Wrap your component tree with <VeloxProvider config={{...}}>.');
+    }
+    return context;
+}
+//# sourceMappingURL=provider.js.map

package/dist/react/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/react/provider.tsx"],"names":[],"mappings":";AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAkB,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAE3E,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,YAAY,GAAG,aAAa,CAAoC,IAAI,CAAC,CAAC;AAE5E,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E;;GAEG;AACH,SAAS,wBAAwB;IAC/B,OAAO,IAAI,WAAW,CAAC;QACrB,cAAc,EAAE;YACd,OAAO,EAAE;gBACP,SAAS,EAAE,MAAM,EAAE,aAAa;gBAChC,KAAK,EAAE,CAAC;gBACR,oBAAoB,EAAE,KAAK;aAC5B;YACD,SAAS,EAAE;gBACT,KAAK,EAAE,CAAC;aACT;SACF;KACF,CAAC,CAAC;AACL,CAAC;AAED,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,MAAM,UAAU,aAAa,CAAU,EACrC,QAAQ,EACR,MAAM,EACN,WAAW,EAAE,mBAAmB,GACJ;IAC5B,6DAA6D;IAC7D,8EAA8E;IAC9E,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,YAAY,CAAU,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEtE,6CAA6C;IAC7C,6CAA6C;IAC7C,MAAM,WAAW,GAAG,OAAO,CACzB,GAAG,EAAE,CAAC,mBAAmB,IAAI,wBAAwB,EAAE,EACvD,CAAC,mBAAmB,CAAC,CACtB,CAAC;IAEF,0DAA0D;IAC1D,MAAM,YAAY,GAAG,OAAO,CAA6B,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEvF,OAAO,CACL,KAAC,YAAY,CAAC,QAAQ,IAAC,KAAK,EAAE,YAA0C,YACtE,KAAC,mBAAmB,IAAC,MAAM,EAAE,WAAW,YAAG,QAAQ,GAAuB,GACpD,CACzB,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,OAAO,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IAEzC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,uDAAuD;YACrD,+DAA+D,CAClE,CAAC;IACJ,CAAC;IAED,OAAO,OAAqC,CAAC;AAC/C,CAAC"}

package/dist/react/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Type definitions for React hooks integration
+ *
+ * Provides type utilities for building type-safe React Query hooks
+ * that work with VeloxTS procedure definitions.
+ *
+ * @module @veloxts/client/react/types
+ */
+import type { UseMutationOptions, UseQueryOptions } from '@tanstack/react-query';
+import type { ClientConfig, ClientFromRouter, InferProcedureInput, InferProcedureOutput, ProcedureCollection } from '../types.js';
+/**
+ * Extracts a specific procedure from the router type
+ *
+ * Enables type inference for procedure input/output in hooks.
+ *
+ * @template TRouter - The router type (collection of procedure collections)
+ * @template TNamespace - The namespace key (e.g., 'users', 'posts')
+ * @template TProcedureName - The procedure name (e.g., 'getUser', 'listUsers')
+ */
+export type GetProcedure<TRouter, TNamespace extends keyof TRouter, TProcedureName extends keyof GetProceduresFromCollection<TRouter[TNamespace]>> = TRouter[TNamespace] extends ProcedureCollection<infer TProcedures> ? TProcedureName extends keyof TProcedures ? TProcedures[TProcedureName] : never : never;
+/**
+ * Extracts the procedures record from a collection
+ *
+ * @template TCollection - The procedure collection type
+ */
+export type GetProceduresFromCollection<TCollection> = TCollection extends ProcedureCollection ? TCollection['procedures'] : never;
+/**
+ * Options for useQuery hook
+ *
+ * Omits queryKey and queryFn since those are provided automatically
+ * based on the procedure namespace, name, and input.
+ *
+ * @template TData - The expected response data type
+ * @template TError - The error type (defaults to Error)
+ */
+export type VeloxUseQueryOptions<TData, TError = Error> = Omit<UseQueryOptions<TData, TError>, 'queryKey' | 'queryFn'>;
+/**
+ * Options for useMutation hook
+ *
+ * Omits mutationFn since that's provided automatically
+ * based on the procedure namespace and name.
+ *
+ * @template TData - The expected response data type
+ * @template TInput - The mutation input type
+ * @template TError - The error type (defaults to Error)
+ * @template TContext - The mutation context type
+ */
+export type VeloxUseMutationOptions<TData, TInput, TError = Error, TContext = unknown> = Omit<UseMutationOptions<TData, TError, TInput, TContext>, 'mutationFn'>;
+/**
+ * Query key structure for VeloxTS
+ *
+ * Format: [namespace, procedureName, input?]
+ *
+ * This structure enables:
+ * - Invalidating all queries for a namespace: `['users']`
+ * - Invalidating a specific procedure: `['users', 'getUser']`
+ * - Invalidating a specific query: `['users', 'getUser', { id: '123' }]`
+ */
+export type VeloxQueryKey = readonly [string, string] | readonly [string, string, Record<string, unknown>];
+/**
+ * Context value provided by VeloxProvider
+ *
+ * @template TRouter - The router type for type-safe client access
+ */
+export interface VeloxContextValue<TRouter> {
+    /** The typed client instance */
+    readonly client: ClientFromRouter<TRouter>;
+}
+/**
+ * Props for VeloxProvider component
+ *
+ * @template _TRouter - The router type for type-safe client configuration (used for generic inference)
+ */
+export interface VeloxProviderProps<_TRouter> {
+    /** React children to render within the provider */
+    readonly children: React.ReactNode;
+    /** Client configuration (baseUrl, headers, etc.) */
+    readonly config: ClientConfig;
+    /** Optional pre-configured QueryClient instance */
+    readonly queryClient?: import('@tanstack/react-query').QueryClient;
+}
+export type { InferProcedureInput, InferProcedureOutput, ProcedureCollection, ClientConfig, ClientFromRouter, };
+//# sourceMappingURL=types.d.ts.map

package/dist/react/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/react/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEjF,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAMrB;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,CACtB,OAAO,EACP,UAAU,SAAS,MAAM,OAAO,EAChC,cAAc,SAAS,MAAM,2BAA2B,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,IAC3E,OAAO,CAAC,UAAU,CAAC,SAAS,mBAAmB,CAAC,MAAM,WAAW,CAAC,GAClE,cAAc,SAAS,MAAM,WAAW,GACtC,WAAW,CAAC,cAAc,CAAC,GAC3B,KAAK,GACP,KAAK,CAAC;AAEV;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,CAAC,WAAW,IAAI,WAAW,SAAS,mBAAmB,GAC1F,WAAW,CAAC,YAAY,CAAC,GACzB,KAAK,CAAC;AAMV;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI,CAC5D,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,EAC9B,UAAU,GAAG,SAAS,CACvB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,QAAQ,GAAG,OAAO,IAAI,IAAI,CAC3F,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EACnD,YAAY,CACb,CAAC;AAMF;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GACrB,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GACzB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAMvD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,OAAO;IACxC,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;CAC5C;AAED;;;;GAIG;AAEH,MAAM,WAAW,kBAAkB,CAAC,QAAQ;IAC1C,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IACnC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,uBAAuB,EAAE,WAAW,CAAC;CACpE;AAMD,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,GACjB,CAAC"}

package/dist/react/types.js

@@ -0,0 +1,10 @@
+/**
+ * Type definitions for React hooks integration
+ *
+ * Provides type utilities for building type-safe React Query hooks
+ * that work with VeloxTS procedure definitions.
+ *
+ * @module @veloxts/client/react/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/react/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/react/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/react/utils.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Utility functions for React Query integration
+ *
+ * Provides query key builders and cache invalidation helpers
+ * for consistent and predictable caching behavior.
+ *
+ * @module @veloxts/client/react/utils
+ */
+import type { QueryClient } from '@tanstack/react-query';
+import type { VeloxQueryKey } from './types.js';
+/**
+ * Builds a stable query key for React Query
+ *
+ * Query keys are structured as: [namespace, procedureName, input?]
+ * This enables efficient cache invalidation by namespace or procedure.
+ *
+ * The key structure follows React Query best practices:
+ * - Keys are arrays for hierarchical invalidation
+ * - Input is serialized for stable identity
+ *
+ * @param namespace - The procedure namespace (e.g., 'users')
+ * @param procedureName - The procedure name (e.g., 'getUser')
+ * @param input - Optional input parameters
+ * @returns A stable query key array
+ *
+ * @example
+ * ```typescript
+ * // Query with no input
+ * buildQueryKey('health', 'check');
+ * // => ['health', 'check']
+ *
+ * // Query with object input
+ * buildQueryKey('users', 'getUser', { id: '123' });
+ * // => ['users', 'getUser', { id: '123' }]
+ *
+ * // Query with primitive input (wrapped)
+ * buildQueryKey('users', 'getCount', 10);
+ * // => ['users', 'getCount', { value: 10 }]
+ * ```
+ */
+export declare function buildQueryKey(namespace: string, procedureName: string, input?: unknown): VeloxQueryKey;
+/**
+ * Invalidates all queries for a namespace
+ *
+ * This is useful after mutations that may affect multiple resources
+ * within the same namespace.
+ *
+ * @param queryClient - The React Query client instance
+ * @param namespace - The namespace to invalidate (e.g., 'users')
+ *
+ * @example
+ * ```typescript
+ * const queryClient = useQueryClient();
+ *
+ * // After deleting a user, invalidate all user queries
+ * await invalidateNamespace(queryClient, 'users');
+ * ```
+ */
+export declare function invalidateNamespace(queryClient: QueryClient, namespace: string): Promise<void>;
+/**
+ * Invalidates all queries for a specific procedure
+ *
+ * This is useful when you want to refetch all instances of a specific
+ * query without affecting other queries in the same namespace.
+ *
+ * @param queryClient - The React Query client instance
+ * @param namespace - The procedure namespace (e.g., 'users')
+ * @param procedureName - The procedure name (e.g., 'getUser')
+ *
+ * @example
+ * ```typescript
+ * const queryClient = useQueryClient();
+ *
+ * // After updating a user, invalidate all getUser queries
+ * await invalidateProcedure(queryClient, 'users', 'getUser');
+ * ```
+ */
+export declare function invalidateProcedure(queryClient: QueryClient, namespace: string, procedureName: string): Promise<void>;
+/**
+ * Invalidates a specific query by its exact key
+ *
+ * This is useful when you know the exact input and want to invalidate
+ * only that specific cached query.
+ *
+ * @param queryClient - The React Query client instance
+ * @param namespace - The procedure namespace (e.g., 'users')
+ * @param procedureName - The procedure name (e.g., 'getUser')
+ * @param input - The exact input used in the query
+ *
+ * @example
+ * ```typescript
+ * const queryClient = useQueryClient();
+ *
+ * // After updating user 123, invalidate only that specific query
+ * await invalidateQuery(queryClient, 'users', 'getUser', { id: '123' });
+ * ```
+ */
+export declare function invalidateQuery(queryClient: QueryClient, namespace: string, procedureName: string, input?: unknown): Promise<void>;
+/**
+ * Gets cached data for a specific query
+ *
+ * Useful for optimistic updates where you need the current cached value.
+ *
+ * @param queryClient - The React Query client instance
+ * @param namespace - The procedure namespace
+ * @param procedureName - The procedure name
+ * @param input - The query input
+ * @returns The cached data or undefined if not cached
+ *
+ * @example
+ * ```typescript
+ * const queryClient = useQueryClient();
+ *
+ * // Get current cached user before optimistic update
+ * const previousUser = getQueryData<User>(
+ *   queryClient,
+ *   'users',
+ *   'getUser',
+ *   { id: '123' }
+ * );
+ * ```
+ */
+export declare function getQueryData<TData>(queryClient: QueryClient, namespace: string, procedureName: string, input?: unknown): TData | undefined;
+/**
+ * Sets cached data for a specific query
+ *
+ * Useful for optimistic updates where you want to update the cache
+ * immediately before the mutation completes.
+ *
+ * @param queryClient - The React Query client instance
+ * @param namespace - The procedure namespace
+ * @param procedureName - The procedure name
+ * @param input - The query input
+ * @param data - The data to cache
+ *
+ * @example
+ * ```typescript
+ * const queryClient = useQueryClient();
+ *
+ * // Optimistically update user in cache
+ * setQueryData<User>(
+ *   queryClient,
+ *   'users',
+ *   'getUser',
+ *   { id: '123' },
+ *   { ...previousUser, name: 'New Name' }
+ * );
+ * ```
+ */
+export declare function setQueryData<TData>(queryClient: QueryClient, namespace: string, procedureName: string, input: unknown, data: TData): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/react/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/react/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAMhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,KAAK,CAAC,EAAE,OAAO,GACd,aAAa,CAYf;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,KAAK,CAAC,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC,CAGf;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAChC,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,KAAK,CAAC,EAAE,OAAO,GACd,KAAK,GAAG,SAAS,CAGnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAChC,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,KAAK,GACV,IAAI,CAGN"}

package/dist/react/utils.js

@@ -0,0 +1,181 @@
+/**
+ * Utility functions for React Query integration
+ *
+ * Provides query key builders and cache invalidation helpers
+ * for consistent and predictable caching behavior.
+ *
+ * @module @veloxts/client/react/utils
+ */
+// ============================================================================
+// Query Key Builders
+// ============================================================================
+/**
+ * Builds a stable query key for React Query
+ *
+ * Query keys are structured as: [namespace, procedureName, input?]
+ * This enables efficient cache invalidation by namespace or procedure.
+ *
+ * The key structure follows React Query best practices:
+ * - Keys are arrays for hierarchical invalidation
+ * - Input is serialized for stable identity
+ *
+ * @param namespace - The procedure namespace (e.g., 'users')
+ * @param procedureName - The procedure name (e.g., 'getUser')
+ * @param input - Optional input parameters
+ * @returns A stable query key array
+ *
+ * @example
+ * ```typescript
+ * // Query with no input
+ * buildQueryKey('health', 'check');
+ * // => ['health', 'check']
+ *
+ * // Query with object input
+ * buildQueryKey('users', 'getUser', { id: '123' });
+ * // => ['users', 'getUser', { id: '123' }]
+ *
+ * // Query with primitive input (wrapped)
+ * buildQueryKey('users', 'getCount', 10);
+ * // => ['users', 'getCount', { value: 10 }]
+ * ```
+ */
+export function buildQueryKey(namespace, procedureName, input) {
+    if (input === undefined || input === null) {
+        return [namespace, procedureName];
+    }
+    // For objects, include directly in key for proper caching
+    if (typeof input === 'object') {
+        return [namespace, procedureName, input];
+    }
+    // For primitives, wrap in object to maintain consistent key structure
+    return [namespace, procedureName, { value: input }];
+}
+// ============================================================================
+// Cache Invalidation Helpers
+// ============================================================================
+/**
+ * Invalidates all queries for a namespace
+ *
+ * This is useful after mutations that may affect multiple resources
+ * within the same namespace.
+ *
+ * @param queryClient - The React Query client instance
+ * @param namespace - The namespace to invalidate (e.g., 'users')
+ *
+ * @example
+ * ```typescript
+ * const queryClient = useQueryClient();
+ *
+ * // After deleting a user, invalidate all user queries
+ * await invalidateNamespace(queryClient, 'users');
+ * ```
+ */
+export async function invalidateNamespace(queryClient, namespace) {
+    await queryClient.invalidateQueries({ queryKey: [namespace] });
+}
+/**
+ * Invalidates all queries for a specific procedure
+ *
+ * This is useful when you want to refetch all instances of a specific
+ * query without affecting other queries in the same namespace.
+ *
+ * @param queryClient - The React Query client instance
+ * @param namespace - The procedure namespace (e.g., 'users')
+ * @param procedureName - The procedure name (e.g., 'getUser')
+ *
+ * @example
+ * ```typescript
+ * const queryClient = useQueryClient();
+ *
+ * // After updating a user, invalidate all getUser queries
+ * await invalidateProcedure(queryClient, 'users', 'getUser');
+ * ```
+ */
+export async function invalidateProcedure(queryClient, namespace, procedureName) {
+    await queryClient.invalidateQueries({ queryKey: [namespace, procedureName] });
+}
+/**
+ * Invalidates a specific query by its exact key
+ *
+ * This is useful when you know the exact input and want to invalidate
+ * only that specific cached query.
+ *
+ * @param queryClient - The React Query client instance
+ * @param namespace - The procedure namespace (e.g., 'users')
+ * @param procedureName - The procedure name (e.g., 'getUser')
+ * @param input - The exact input used in the query
+ *
+ * @example
+ * ```typescript
+ * const queryClient = useQueryClient();
+ *
+ * // After updating user 123, invalidate only that specific query
+ * await invalidateQuery(queryClient, 'users', 'getUser', { id: '123' });
+ * ```
+ */
+export async function invalidateQuery(queryClient, namespace, procedureName, input) {
+    const queryKey = buildQueryKey(namespace, procedureName, input);
+    await queryClient.invalidateQueries({ queryKey });
+}
+// ============================================================================
+// Cache Data Accessors
+// ============================================================================
+/**
+ * Gets cached data for a specific query
+ *
+ * Useful for optimistic updates where you need the current cached value.
+ *
+ * @param queryClient - The React Query client instance
+ * @param namespace - The procedure namespace
+ * @param procedureName - The procedure name
+ * @param input - The query input
+ * @returns The cached data or undefined if not cached
+ *
+ * @example
+ * ```typescript
+ * const queryClient = useQueryClient();
+ *
+ * // Get current cached user before optimistic update
+ * const previousUser = getQueryData<User>(
+ *   queryClient,
+ *   'users',
+ *   'getUser',
+ *   { id: '123' }
+ * );
+ * ```
+ */
+export function getQueryData(queryClient, namespace, procedureName, input) {
+    const queryKey = buildQueryKey(namespace, procedureName, input);
+    return queryClient.getQueryData(queryKey);
+}
+/**
+ * Sets cached data for a specific query
+ *
+ * Useful for optimistic updates where you want to update the cache
+ * immediately before the mutation completes.
+ *
+ * @param queryClient - The React Query client instance
+ * @param namespace - The procedure namespace
+ * @param procedureName - The procedure name
+ * @param input - The query input
+ * @param data - The data to cache
+ *
+ * @example
+ * ```typescript
+ * const queryClient = useQueryClient();
+ *
+ * // Optimistically update user in cache
+ * setQueryData<User>(
+ *   queryClient,
+ *   'users',
+ *   'getUser',
+ *   { id: '123' },
+ *   { ...previousUser, name: 'New Name' }
+ * );
+ * ```
+ */
+export function setQueryData(queryClient, namespace, procedureName, input, data) {
+    const queryKey = buildQueryKey(namespace, procedureName, input);
+    queryClient.setQueryData(queryKey, data);
+}
+//# sourceMappingURL=utils.js.map

package/dist/react/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/react/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,aAAa,CAC3B,SAAiB,EACjB,aAAqB,EACrB,KAAe;IAEf,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,OAAO,CAAC,SAAS,EAAE,aAAa,CAAU,CAAC;IAC7C,CAAC;IAED,0DAA0D;IAC1D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,CAAC,SAAS,EAAE,aAAa,EAAE,KAAgC,CAAU,CAAC;IAC/E,CAAC;IAED,sEAAsE;IACtE,OAAO,CAAC,SAAS,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAU,CAAC;AAC/D,CAAC;AAED,+EAA+E;AAC/E,6BAA6B;AAC7B,+EAA+E;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,WAAwB,EACxB,SAAiB;IAEjB,MAAM,WAAW,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,WAAwB,EACxB,SAAiB,EACjB,aAAqB;IAErB,MAAM,WAAW,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,CAAC,SAAS,EAAE,aAAa,CAAC,EAAE,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,WAAwB,EACxB,SAAiB,EACjB,aAAqB,EACrB,KAAe;IAEf,MAAM,QAAQ,GAAG,aAAa,CAAC,SAAS,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC;IAChE,MAAM,WAAW,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;AACpD,CAAC;AAED,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,YAAY,CAC1B,WAAwB,EACxB,SAAiB,EACjB,aAAqB,EACrB,KAAe;IAEf,MAAM,QAAQ,GAAG,aAAa,CAAC,SAAS,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC;IAChE,OAAO,WAAW,CAAC,YAAY,CAAQ,QAAQ,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,YAAY,CAC1B,WAAwB,EACxB,SAAiB,EACjB,aAAqB,EACrB,KAAc,EACd,IAAW;IAEX,MAAM,QAAQ,GAAG,aAAa,CAAC,SAAS,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC;IAChE,WAAW,CAAC,YAAY,CAAQ,QAAQ,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC"}

package/dist/test-setup.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Test setup file for Vitest
+ *
+ * Sets up jest-dom matchers for React Testing Library
+ */
+import '@testing-library/jest-dom/vitest';
+//# sourceMappingURL=test-setup.d.ts.map

package/dist/test-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-setup.d.ts","sourceRoot":"","sources":["../src/test-setup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,kCAAkC,CAAC"}

package/dist/test-setup.js

@@ -0,0 +1,7 @@
+/**
+ * Test setup file for Vitest
+ *
+ * Sets up jest-dom matchers for React Testing Library
+ */
+import '@testing-library/jest-dom/vitest';
+//# sourceMappingURL=test-setup.js.map

package/dist/test-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-setup.js","sourceRoot":"","sources":["../src/test-setup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,kCAAkC,CAAC"}