@openapi-qraft/react 2.8.0 → 2.10.0

package/src/lib/urlSerializer.test.ts

@@ -14,6 +14,38 @@ describe('urlSerializer', () => {
     ).toBe('https://api.example.com/users/123/posts/456');
   });
 
+  it('should correctly encode complex characters in path and query parameters', () => {
+    const info = {
+      baseUrl: 'https://api.example.com',
+      parameters: {
+        path: {
+          query: 'hello/world:test@domain.com',
+          category: 'books & magazines',
+        },
+        query: {
+          filter: 'price:$10-$50',
+          tags: ['tag/with/slash', 'tag:with:colon'],
+          special: 'symbols!@#$%^&*()+={}[]|\\:";\'<>?,./~`',
+        },
+      },
+    } as const;
+
+    const result = urlSerializer(
+      { url: '/search/{query}/category/{category}', method: 'get' },
+      info
+    );
+
+    const expectedUrl = new URL(
+      'https://api.example.com/search/hello%2Fworld%3Atest%40domain.com/category/books%20%26%20magazines'
+    );
+    expectedUrl.searchParams.set('filter', info.parameters.query.filter);
+    expectedUrl.searchParams.append('tags', info.parameters.query.tags[0]);
+    expectedUrl.searchParams.append('tags', info.parameters.query.tags[1]);
+    expectedUrl.searchParams.set('special', info.parameters.query.special);
+
+    expect(result).toBe(expectedUrl.toString());
+  });
+
   it('should correctly append query parameters', () => {
     expect(
       urlSerializer(
@@ -215,4 +247,237 @@ describe('urlSerializer', () => {
       )
     ).toBe('https://api.example.com/users/undefined/posts/456');
   });
+
+  it('should correctly serialize query parameters with Date objects', () => {
+    expect(
+      urlSerializer(
+        { url: '/events', method: 'get' },
+        {
+          baseUrl: 'https://api.example.com',
+          parameters: {
+            query: {
+              startDate: new Date('2023-12-25T10:30:00.000Z'),
+              limit: 5,
+            },
+          },
+        }
+      )
+    ).toBe(
+      `https://api.example.com/events?startDate=2023-12-25T10%3A30%3A00.000Z&limit=5`
+    );
+  });
+
+  it('should correctly serialize query parameters with Date objects in arrays', () => {
+    expect(
+      urlSerializer(
+        { url: '/events', method: 'get' },
+        {
+          baseUrl: 'https://api.example.com',
+          parameters: {
+            query: {
+              dates: [
+                new Date('2023-01-01T00:00:00.000Z'),
+                new Date('2023-12-31T23:59:59.999Z'),
+              ],
+              active: true,
+            },
+          },
+        }
+      )
+    ).toBe(
+      'https://api.example.com/events?dates=2023-01-01T00%3A00%3A00.000Z&dates=2023-12-31T23%3A59%3A59.999Z&active=true'
+    );
+  });
+
+  it('should correctly serialize query parameters with Date objects in nested objects', () => {
+    const startDate = new Date('2023-01-01T00:00:00.000Z');
+    expect(
+      urlSerializer(
+        { url: '/events', method: 'get' },
+        {
+          baseUrl: 'https://api.example.com',
+          parameters: {
+            query: {
+              timeRange: {
+                start: startDate,
+                end: null,
+              },
+              limit: 10,
+            },
+          },
+        }
+      )
+    ).toBe(
+      'https://api.example.com/events?timeRange%5Bstart%5D=2023-01-01T00%3A00%3A00.000Z&limit=10'
+    );
+  });
+
+  it('should correctly serialize query parameters with boolean values', () => {
+    expect(
+      urlSerializer(
+        { url: '/users', method: 'get' },
+        {
+          baseUrl: 'https://api.example.com',
+          parameters: {
+            query: {
+              active: true,
+              verified: false,
+              premium: null,
+              limit: 10,
+            },
+          },
+        }
+      )
+    ).toBe('https://api.example.com/users?active=true&verified=false&limit=10');
+  });
+
+  it('should correctly serialize query parameters with numeric values', () => {
+    expect(
+      urlSerializer(
+        { url: '/products', method: 'get' },
+        {
+          baseUrl: 'https://api.example.com',
+          parameters: {
+            query: {
+              price: 0,
+              discount: 25.5,
+              quantity: -1,
+              maxPrice: 1000,
+            },
+          },
+        }
+      )
+    ).toBe(
+      'https://api.example.com/products?price=0&discount=25.5&quantity=-1&maxPrice=1000'
+    );
+  });
+
+  it('should correctly serialize query parameters with special numeric values', () => {
+    expect(
+      urlSerializer(
+        { url: '/data', method: 'get' },
+        {
+          baseUrl: 'https://api.example.com',
+          parameters: {
+            query: {
+              infinity: Infinity,
+              negativeInfinity: -Infinity,
+              notANumber: NaN,
+              normal: 42,
+            },
+          },
+        }
+      )
+    ).toBe(
+      'https://api.example.com/data?infinity=Infinity&negativeInfinity=-Infinity&notANumber=NaN&normal=42'
+    );
+  });
+
+  it('should correctly serialize query parameters with empty string values', () => {
+    expect(
+      urlSerializer(
+        { url: '/search', method: 'get' },
+        {
+          baseUrl: 'https://api.example.com',
+          parameters: {
+            query: {
+              query: '',
+              category: 'books',
+              sort: null,
+            },
+          },
+        }
+      )
+    ).toBe('https://api.example.com/search?query=&category=books');
+  });
+
+  it('should correctly serialize deeply nested objects', () => {
+    expect(
+      urlSerializer(
+        { url: '/complex', method: 'get' },
+        {
+          baseUrl: 'https://api.example.com',
+          parameters: {
+            query: {
+              level1: {
+                level2: {
+                  level3: {
+                    value: 'deep',
+                    number: 42,
+                  },
+                  array: ['a', 'b'],
+                },
+              },
+              simple: 'value',
+            },
+          },
+        }
+      )
+    ).toBe(
+      'https://api.example.com/complex?level1%5Blevel2%5D%5Blevel3%5D%5Bvalue%5D=deep&level1%5Blevel2%5D%5Blevel3%5D%5Bnumber%5D=42&level1%5Blevel2%5D%5Barray%5D=a&level1%5Blevel2%5D%5Barray%5D=b&simple=value'
+    );
+  });
+
+  it('should correctly serialize mixed arrays with different types', () => {
+    const testDate = new Date('2023-06-15T12:00:00.000Z');
+    expect(
+      urlSerializer(
+        { url: '/mixed', method: 'get' },
+        {
+          baseUrl: 'https://api.example.com',
+          parameters: {
+            query: {
+              mixed: ['string', 123, true, testDate, null, undefined],
+              clean: 'value',
+            },
+          },
+        }
+      )
+    ).toBe(
+      'https://api.example.com/mixed?mixed=string&mixed=123&mixed=true&mixed=2023-06-15T12%3A00%3A00.000Z&clean=value'
+    );
+  });
+
+  it('should handle objects with arrays containing objects', () => {
+    expect(
+      urlSerializer(
+        { url: '/nested-array-objects', method: 'get' },
+        {
+          baseUrl: 'https://api.example.com',
+          parameters: {
+            query: {
+              items: [
+                { name: 'item1', value: 100 },
+                { name: 'item2', value: null },
+              ],
+              total: 2,
+            },
+          },
+        }
+      )
+    ).toBe(
+      'https://api.example.com/nested-array-objects?items%5Bname%5D=item1&items%5Bvalue%5D=100&items%5Bname%5D=item2&total=2'
+    );
+  });
+
+  it('should handle edge cases with String() conversion', () => {
+    // Test to verify correct processing of different types of data
+    expect(
+      urlSerializer(
+        { url: '/edge-cases', method: 'get' },
+        {
+          baseUrl: 'https://api.example.com',
+          parameters: {
+            query: {
+              bigint: BigInt(123),
+              symbol: 'symbol-as-string', // Symbol cannot be serialized directly
+              func: '[Function]', // Functions should not get into query, but if they do - as a string
+            },
+          },
+        }
+      )
+    ).toBe(
+      'https://api.example.com/edge-cases?bigint=123&symbol=symbol-as-string&func=%5BFunction%5D'
+    );
+  });
 });

package/src/qraftAPIClient.ts

@@ -115,8 +115,23 @@ export function qraftAPIClient<
 ): APIBasicQueryClientServices<Services, Callbacks>;
 
 /**
- * Creates a basic API Client which contains only "fetch" like
- * operations without any state management using QueryClient.
+ * Creates a basic API Client which contains all hooks and methods
+ * that don't require an explicitly provided QueryClient.
+ * Hooks like `useQuery` and `useMutation` will automatically retrieve
+ * the QueryClient from the `<QueryClientProvider />` context.
+ *
+ * @example Fetching data with QueryClient from context
+ * ```ts
+ * const api = qraftAPIClient(services, callbacks, {
+ *   requestFn: requestFn,
+ *   baseUrl: 'https://api.example.com',
+ * });
+ *
+ * // QueryClient will be retrieved from React context
+ * api.service.operation.useQuery({
+ *   parameters: { path: { id: 1 } },
+ * });
+ * ```
  *
  * @example Fetching data without QueryClient
  * ```ts
@@ -140,8 +155,17 @@ export function qraftAPIClient<
 ): APIBasicClientServices<Services, Callbacks>;
 
 /**
- * Creates a utility API Client which contains only utility operations
- * such as `getQueryKey`, `getInfiniteQueryKey` and `getMutationKey`.
+ * Creates a utility API Client which contains utility operations
+ * such as `getQueryKey`, `getInfiniteQueryKey`, `getMutationKey` and state hooks
+ * like `useIsFetching` and `useMutationData`.
+ *
+ * @example Using state hooks
+ * ```ts
+ * const api = qraftAPIClient(services, callbacks);
+ *
+ * // Check if any query is currently fetching
+ * const isFetching = api.service.operation.useIsFetching();
+ * ```
  *
  * @example Getting query keys with utility client
  * ```ts
@@ -241,7 +265,17 @@ export function qraftAPIClient<
         callbackName !== 'operationInvokeFn' &&
         callbackName !== 'getQueryKey' &&
         callbackName !== 'getMutationKey' &&
-        callbackName !== 'getInfiniteQueryKey'
+        callbackName !== 'getInfiniteQueryKey' &&
+        callbackName !== 'useInfiniteQuery' &&
+        callbackName !== 'useQueries' &&
+        callbackName !== 'useQuery' &&
+        callbackName !== 'useSuspenseInfiniteQuery' &&
+        callbackName !== 'useSuspenseQueries' &&
+        callbackName !== 'useSuspenseQuery' &&
+        callbackName !== 'useIsFetching' &&
+        callbackName !== 'useMutation' &&
+        callbackName !== 'useIsMutating' &&
+        callbackName !== 'useMutationState'
       )
         if (!options || !('queryClient' in options && options.queryClient))
           throw new Error(
@@ -331,7 +365,7 @@ type OperationDeclaration = {
     Record<
       | QueryOperationCallbacks
       | QueryOperationStateCallbacks
-      | MutationOperationCallbacks
+      | MutationOperationHookCallbacks
       | MutationOperationStateCallbacks
       | UtilityOperationCallbacks,
       any
@@ -356,15 +390,8 @@ export type UnionServiceOperationsDeclaration<Services> =
   | OperationsDeclaration<Services>
   | OperationDeclaration;
 
-type QueryOperationCallbacks = Extract<
+type QueryOperationHookCallbacks = Extract<
   keyof ServiceMethods,
-  | 'fetchInfiniteQuery'
-  | 'fetchQuery'
-  | 'prefetchInfiniteQuery'
-  | 'prefetchQuery'
-  | 'refetchQueries'
-  | 'ensureQueryData'
-  | 'ensureInfiniteQueryData'
   | 'useInfiniteQuery'
   | 'useQueries'
   | 'useQuery'
@@ -373,31 +400,57 @@ type QueryOperationCallbacks = Extract<
   | 'useSuspenseQuery'
 >;
 
-type QueryOperationStateCallbacks = Extract<
+type QueryOperationCallbacks =
+  | Extract<
+      keyof ServiceMethods,
+      | 'fetchInfiniteQuery'
+      | 'fetchQuery'
+      | 'prefetchInfiniteQuery'
+      | 'prefetchQuery'
+      | 'refetchQueries'
+      | 'ensureQueryData'
+      | 'ensureInfiniteQueryData'
+    >
+  | QueryOperationHookCallbacks;
+
+type QueryOperationStateHookCallbacks = Extract<
   keyof ServiceMethods,
-  | 'cancelQueries'
-  | 'getInfiniteQueryData'
-  | 'getInfiniteQueryState'
-  | 'getQueriesData'
-  | 'getQueryData'
-  | 'getQueryState'
-  | 'invalidateQueries'
-  | 'isFetching'
-  | 'removeQueries'
-  | 'resetQueries'
-  | 'setInfiniteQueryData'
-  | 'setQueriesData'
-  | 'setQueryData'
-  | 'useIsFetching'
+  'useIsFetching'
 >;
 
-type MutationOperationCallbacks = Extract<keyof ServiceMethods, 'useMutation'>;
+type QueryOperationStateCallbacks =
+  | Extract<
+      keyof ServiceMethods,
+      | 'cancelQueries'
+      | 'getInfiniteQueryData'
+      | 'getInfiniteQueryState'
+      | 'getQueriesData'
+      | 'getQueryData'
+      | 'getQueryState'
+      | 'invalidateQueries'
+      | 'isFetching'
+      | 'removeQueries'
+      | 'resetQueries'
+      | 'setInfiniteQueryData'
+      | 'setQueriesData'
+      | 'setQueryData'
+    >
+  | QueryOperationStateHookCallbacks;
 
-type MutationOperationStateCallbacks = Extract<
+type MutationOperationHookCallbacks = Extract<
   keyof ServiceMethods,
-  'isMutating' | 'useIsMutating' | 'useMutationState'
+  'useMutation'
 >;
 
+type MutationOperationStateHookCallbacks = Extract<
+  keyof ServiceMethods,
+  'useIsMutating' | 'useMutationState'
+>;
+
+type MutationOperationStateCallbacks =
+  | Extract<keyof ServiceMethods, 'isMutating'>
+  | MutationOperationStateHookCallbacks;
+
 type InvokeOperationCallback = Extract<
   keyof typeof operationInvokeModule,
   'operationInvokeFn'
@@ -405,13 +458,17 @@ type InvokeOperationCallback = Extract<
 
 type UtilityOperationCallbacks = Extract<
   keyof ServiceMethods,
-  'getQueryKey' | 'getInfiniteQueryKey' | 'getMutationKey'
+  | 'getQueryKey'
+  | 'getInfiniteQueryKey'
+  | 'getMutationKey'
+  | QueryOperationStateHookCallbacks
+  | MutationOperationStateHookCallbacks
 >;
 
 type OperationCallbackList =
   | QueryOperationCallbacks
   | QueryOperationStateCallbacks
-  | MutationOperationCallbacks
+  | MutationOperationHookCallbacks
   | MutationOperationStateCallbacks
   | InvokeOperationCallback
   | UtilityOperationCallbacks;
@@ -458,7 +515,15 @@ export type APIBasicClientServices<
   Callbacks extends PartialServiceMethods,
 > = ServicesFilteredByCallbacks<
   Services,
-  Extract<keyof Callbacks, InvokeOperationCallback | UtilityOperationCallbacks>
+  Extract<
+    keyof Callbacks,
+    | InvokeOperationCallback
+    | UtilityOperationCallbacks
+    | QueryOperationHookCallbacks
+    | QueryOperationStateHookCallbacks
+    | MutationOperationStateHookCallbacks
+    | MutationOperationHookCallbacks
+  >
 >;
 
 export type APIUtilityClientServices<